Texera Documentation

• 1: Overview
• 2: Getting Started
• 2.1: Single Node Installation
• 2.2: Access/Login to Texera
• 2.3: Texera UI Overview
• 3: Concepts
• 4: Examples
• 5: Tutorials
• 6: Reference
• 6.1: Configuration
• 6.2: Project Structure
• 6.3: Engine
• 6.4: Operators
• 6.5: Frontend
• 6.6: Storage
• 7: Contribution Guidelines
• 8: Operators
• 9: Security

1 - Overview

Texera combines powerful backend dataflow execution with an intuitive, drag-and-drop web interface.
It’s ideal for building, executing, and sharing complex data workflows across teams.

Key Features

• Web-based workflows: no installation required on clients.
• Collaborative editing: multiple users can build together.
• Scalable execution: distributed workflow execution engine.
• Extensible: easy to develop new operators and visual components.

Texera enables you to move from prototype to production data pipelines seamlessly.

2 - Getting Started

Launch Texera

Follow the Single Node Instruction or
the Guide for Developers to start the system.

Once Texera is running, open your web browser and navigate to its local URL.

http://localhost:4200

2.1 - Single Node Installation

Prerequisites

Before starting, make sure your computer meets the following requirements:

You also need to install and launch Docker Desktop on your computer. Choose the right installation link for your computer:

After installing and launching Docker Desktop, verify that Docker and Docker Compose are available by running the following commands from the command line:

docker --version
docker compose version

You should see output messages like the following (your versions may be different):

$ docker --version
Docker version 27.5.1, build 9f9e405
$ docker compose version
Docker Compose version v2.23.0-desktop.1

Download Texera Installer (a few kilobytes)

Download texera-single-node-release and extract it.

Launch Texera

Go to the extracted directory using the following command:

cd apache-texera-incubating-release-1-1-0-single-node

Run the following command to start Texera:

docker compose up

If you see the error message like unable to get image 'nginx:alpine': Cannot connect to the Docker daemon at unix:///Users/kunwoopark/.docker/run/docker.sock. Is the docker daemon running?, please make sure Docker Desktop is installed and running

When you start Texera for the first time, it will take around 5 minutes to download needed images. If you enable the R support, it will take around 20 minutes

The system is ready when you see the following messages:

......
texera-access-message              | ===============================================
texera-access-message              | Texera is ready!
texera-access-message              | ===============================================
texera-access-message              | 
texera-access-message              | To access Texera, open your browser and navigate to:
texera-access-message              |     http://localhost:8080
texera-access-message              | 
texera-access-message              | The following account has been created for you:
texera-access-message              |     Username: texera
texera-access-message              |     Password: texera
texera-access-message              | 
texera-access-message              | ===============================================
......
some health check messages
......

Open your browser and navigate to:

http://localhost:8080

An account texera with password texera is already setup and pre-filled for you. You can click on the Sign In button to login:

You should see the following page:

Note: Texera does NOT support R operators by default. To enable R support, refer to the Advanced Settings section.

Stop, Restart, and Uninstall Texera

Stop

Press Ctrl+C in the terminal to stop Texera.

If you already closed the terminal, you can go to the installation folder and run:

docker compose stop

to stop Texera.

Restart

Same as the way you launch Texera.

Uninstall

To remove Texera and all its data, go to the installation folder and run:

docker compose down -v

⚠️ Warning: This will permanently delete all the data used by Texera.

Advanced Settings

Before making any of the changes below, please stop Texera first. Once you finish the changes, restart Texera to apply them.

All changes are to the docker-compose.yml file in the installation folder.

Enable Support of the R Programming Language

To support R user-defined-function (UDF) operators, find the computing-unit-master section and change the image tag from release-1-1-0 to release-1-1-0-R.

Run Texera on other ports

By default, Texera uses:

• Port 8080 for its web service
• Port 9000 for its MinIO storage service

To change these ports:

• For the web service port (8080):
  • Find the nginx service section and change the port mapping from "8080:8080" to your desired port mapping, e.g., "8081:8080".
  • Find the texera-access-message service section and change the port in ${TEXERA_HOST}:8080 to your desired port, e.g. ${TEXERA_HOST}:8081
• For the MinIO port (9000):
  • Find the minio service section and change the port mapping from "9000:9000" to your desired port mapping, e.g., "9001:9000".
  • Find the lakefs service section and update the port number of the LAKEFS_BLOCKSTORE_S3_PRE_SIGNED_ENDPOINT from 9000 to your desired port, e.g., 9001.

Change the locations of Texera data

By default, Docker manages Texera’s data locations. To change them to your own locations:

• Find the persistent volumes section. For each data volume you want to specify, add the following configuration:

  volume_name:
    driver: local
    driver_opts:
      type: none
      o: bind
      device: /path/to/your/local/folder
  

  For example, to change the folder of storing workflow_result_data to /Users/johndoe/texera/data, add the following:

  workflow_result_data:
    driver: local
    driver_opts:
      type: none
      o: bind
      device: /Users/johndoe/texera/data
  

If you already launched texera and want to change the data locations, existing data volumes need to be recreated and override in the next boot-up, i.e. select y when running docker compose up again:

$ docker compose up
? Volume "texera-single-node-release-1-1-0_workflow_result_data" exists but doesn't match configuration in compose file. Recreate (data will be lost)? (y/N)
y // answer y to this prompt

2.2 - Access/Login to Texera

Prerequisites

We assume you either went through

• Single Node Instruction, or
• Guide for Texera Developers.

Texera should be up-and-running on your laptop before proceeding.

Access Texera through Browser

Enter Texera’s URL in your browser to access the interface.

By default, an admin account is pre-created:

Input credentials and click the Sign in button to log in as the admin.

2.3 - Texera UI Overview

User Dashboard

Once logged in, you should see the following page:

Navigation Bar

On the left sidebar, you can switch between different resource modules:

• Workflows — manage workflow projects.
• Datasets — upload and manage data files.
• Quota — check usage statistics and resource consumption.
• Admin — manage system users (visible only to admins).

3 - Concepts

Understanding Texera conceptually helps both users and contributors get the most out of the system.

For end users, it provides background on how workflows and operators interact to process data.
For contributors, it offers insight into the design principles and architecture that power Texera’s engine and user interface.

What’s in this section

The Concepts section introduces the core ideas that define Texera’s design and operation:

• Workflows: How users visually build and manage data pipelines.
• Operators: The modular units that perform data transformations.
• Execution Engine: The core component that executes workflows efficiently.
• Data Model: How Texera represents, stores, and streams data.
• Architecture: The high-level structure connecting frontend, backend, and execution layers.

Each page below explores one of these areas in more depth, explaining how Texera’s internal components work together to support flexible, scalable, and interactive data analytics.

When to read this section

If you’re new to Texera, start with the Overview page to understand what the platform does.
Then come here to learn how it works under the hood.

If you’re contributing to Texera or integrating it with other systems, the detailed concept pages — such as Engine, Operator Framework, and Architecture — will help you understand Texera’s internal design and extension points.

4 - Examples

Texera makes it easy to design and execute data analytics workflows visually.
Here, you’ll find a collection of example workflows that highlight Texera’s capabilities — from data ingestion and transformation to visualization and machine learning.

🧩 Example Workflows

Each example demonstrates how Texera operators can be combined to solve different types of data problems.

• Text Analytics Workflow
  Analyze text data using tokenization, keyword extraction, and word cloud visualization.
  → See the Text Analytics Example

• Join and Filter Workflow
  Combine multiple datasets using joins and filters to create complex data pipelines.
  → See the Join Operator Example

• Machine Learning Workflow
  Build end-to-end ML workflows with data preprocessing, model training, and evaluation operators.
  → See the Machine Learning Example

• Visualization Workflow
  Explore Texera’s interactive visual operators like scatter plots, histograms, and word clouds.
  → See the Visualization Example

💡 How to Run the Examples

To try these examples on your local Texera instance:

1. Launch Texera following the Getting Started guide.
2. Open the Workflow Editor in your browser at http://localhost:4200.
3. Import an example workflow file (.json) from the Texera Example Repository.
4. Run the workflow to see Texera’s operators and data visualizations in action.

🧠 Want to Contribute an Example?

If you’ve built your own workflow and want to share it:

• Fork the Texera repository.
• Add your workflow under examples/ with a short README.
• Submit a pull request following our Contribution Guidelines.

These examples are a great starting point for learning Texera’s visual programming model and understanding how different operators interact to form powerful data pipelines.

5 - Tutorials

Texera tutorials help you learn by doing.
Each tutorial walks through a realistic workflow scenario, showing how to use Texera’s visual interface, operators, and execution engine to build and run data analytics applications.

🎯 What to Expect

The tutorials in this section will help you:

• Understand Texera’s workflow-based design step by step.
• Learn how to connect operators, configure parameters, and visualize results.
• Explore practical data use cases, such as text processing, joining datasets, and real-time analysis.
• Get comfortable with extending Texera by creating or modifying operators.

🧱 Structure

Each tutorial consists of:

1. Goal Overview – what you’ll build and what problem it solves.
2. Step-by-Step Instructions – detailed actions to complete the workflow.
3. Key Takeaways – concepts and Texera features you’ll learn.
4. Next Steps – related tutorials or examples to explore further.

🧭 Getting Started

If you’re new to Texera, start with the Getting Started guide to set up your local environment.
Once Texera is running, return here to begin working through the tutorials in order.

📚 Available Tutorials

This section will include multiple tutorials, such as:

• Building your first workflow
• Exploring data transformation operators
• Working with visualization tools
• Combining multiple datasets
• Extending Texera with custom operators

Each tutorial will include screenshots, sample data, and workflow files you can download and import into your Texera instance.

💡 Want to Contribute a Tutorial?

If you’ve built a useful workflow or want to help new users learn Texera, you can contribute your own tutorial:

1. Create a Markdown page under content/docs/tutorials/.
2. Include any relevant .json workflow files or sample datasets.
3. Submit a pull request following our Contribution Guidelines.

Texera tutorials are designed to help you go from understanding concepts to building complete solutions — one workflow at a time.

6 - Reference

The Reference section provides look-up documentation for developers and maintainers who need specific, technical information about Texera’s internals or environment.
Unlike the Concepts section, which explains how Texera works, this section focuses on how Texera is configured, built, and extended.

What you’ll find here

This section includes reference information for:

• Configuration and Environment Setup: Detailed parameters and environment variables used for development, deployment, and testing.
• Project Structure: Explanation of major code directories, module dependencies, and naming conventions.
• Execution Engine Details: Low-level reference for engine modules, operators’ lifecycle, and workflow translation.
• Operator Framework: Technical notes on operator registration, metadata, and extension mechanisms.
• Frontend Components: Descriptions of UI module structure, Angular components, and visualization hooks.
• Persistence and Storage: Information about Texera’s internal storage models, catalog, and workflow metadata.

When to use this section

Use this section when you need:

• To understand or modify Texera’s internal modules or configuration files.
• To debug, extend, or refactor parts of the codebase.
• To deploy Texera in a local, testing, or production environment and need to adjust settings or dependencies.

How to maintain this section

Reference pages are often technical and version-specific. Keep them up to date by:

• Linking or embedding auto-generated documentation from code comments (e.g., Javadoc for backend modules or TypeDoc for frontend).
• Including manual reference pages for configuration files, startup scripts, and architecture diagrams.
• Updating this section whenever internal modules or configuration formats change.

Suggested subpages

This section is meant to be a developer’s technical handbook for Texera’s internal systems — a precise reference for anyone maintaining, extending, or deploying the platform.

6.1 - Configuration

6.2 - Project Structure

6.3 - Engine

6.4 - Operators

6.5 - Frontend

6.6 - Storage

7 - Contribution Guidelines

Contributing to Texera

Texera welcomes contributions from everyone — whether you’re fixing a small bug, improving documentation, or adding new features.

👥 Roles in the Project

🛠 How to Contribute Code

1. Fork the Repository

Fork the Texera repository on GitHub and clone it locally.

2. Find or Open an Issue

• Pick an existing issue or create a new one describing your proposal or bug.
• Discuss your approach with committers before coding to reach consensus.

3. Create and Submit a Pull Request

• Develop in a new branch of your fork.
• When ready, submit a PR to the main Texera repository.
• Allow edits from maintainers to let committers make small fixes if needed.

PR Title and Commit Format

We use Conventional Commits:

• Example PR titles:
  • feat: add new join operator
  • fix(ui): resolve workflow panel crash
  • chore(deps): bump dependency versions
• The PR title becomes the final squashed commit message upon merge.

PR Description Should Include:

• Purpose: use Closes #1234 to auto-close an issue.
• Summary: short overview of your changes.
• Optional: design document, technical diagram, or screenshots.

Avoid including:

• Local config files (e.g., python_udf.conf)
• Secrets or credentials
• Binary or build artifacts

🧪 Testing and Quality Checks

Backend (Scala)

1. Run lint:

   sbt "scalafixAll --check"
   

   Fix with:

   sbt scalafixAll
   

2. Run formatter:

   sbt scalafmtCheckAll
   

   Fix with:

   sbt scalafmtAll
   

3. Execute tests:

   cd core
   sbt test
   

For IntelliJ users: ensure the working directory matches the module (amber for engine tests, core for services).

Frontend (Angular)

1. Run unit tests:

   cd core/gui
   ng test --watch=false
   

2. Format code:

   yarn format:fix
   

Write .spec.ts tests for new functionality to ensure future safety.

🔍 Pull Request Review Process

1. Request a committer to review your PR.
2. Add labels (e.g., fix, enhancement, docs).
3. Wait for CI to pass (GitHub Actions).
4. Mark your PR as draft if it’s not ready.
5. Once approved, a committer will merge your PR.

📝 Apache License Header

All new files must include the Apache License header.
To automate this in IntelliJ:

1. Go to Settings → Editor → Copyright → Copyright Profiles.
2. Create a profile named Apache and add:

   Licensed to the Apache Software Foundation (ASF) under one
   or more contributor license agreements. See the NOTICE file
   distributed with this work for additional information
   regarding copyright ownership...
   

3. Set this as the default profile for the project.

✍️ Contributing to Documentation

Texera uses Hugo and the Docsy theme to build its website.
All documentation is stored in the Texera GitHub repository.

Quick Steps

1. Click Edit this page at the top of any doc page to edit directly on GitHub.
2. Make your edits and open a Pull Request.
3. The site auto-deploys a preview for review via Netlify.
4. Wait for approval and merge.

Preview Locally

To preview locally:

hugo server

Visit http://localhost:1313 to view the site as you edit.

📚 Resources

• Texera GitHub Repository
• Conventional Commits Spec
• Hugo Documentation
• Docsy Guide
• GitHub Pull Request Docs

8 - Operators

9 - Security

Table of Contents

• Security Model Overview
• Resources in Texera
• User Categories and Responsibilities
• UI User Roles and Privileges
• Deployments and Computing Units
• What is NOT a Security Issue
• Reporting Security Vulnerabilities

Security Model Overview

Texera’s security architecture is built around:

1. Authentication: JWT-based token authentication with configurable expiration
2. Authorization: Role-based access control (RBAC) with four user roles
3. Resource Access Control: Fine-grained privileges for datasets, workflows, and computing units
4. Deployment Isolation: Separate security considerations for different deployment modes

Resources in Texera

In Texera, a resource is any object within the system that can be created, accessed, modified, or shared by users via the web application. Understanding resource types and how access to them is managed is critical to following Texera’s security model.

Resource Types

Texera supports the following resource types:

• Datasets: Input data imported or uploaded for workflow processing
• Workflows: Data analytics pipelines defined by users
• Computing Units: Execution environments for running workflows (e.g., Kubernates PODs)
• Results: Output from workflow executions, including but not limited to data, logs, metrics, and visualizations

Resource Ownership and Access Control

Every resource is owned by a user. The owner controls the resource’s visibility and can share it with other users by granting access permissions:

• READ: View the resource and its contents
• WRITE: Modify, execute, delete, and share the resource
• NONE: No access to the resource

Resources can be shared with specific users or made public. Public resources are visible to all users. Resource owners can modify access permissions at any time.

Resource Visibility

• Users can only see resources for which they have at least READ access.
• Access changes (e.g., revoking WRITE or READ) take effect immediately for affected users.

User Categories and Responsibilities

Texera’s security model distinguishes between two categories of users with distinct responsibilities:

Deployment Managers

They have the highest level of access and control. They install and configure Texera, and make decisions about technologies, deployment modes, and permissions. They can potentially delete the entire installation and have access to all credentials, including database passwords, JWT secrets, and API keys. Deployment managers have full access to:

• The underlying infrastructure (servers, Kubernetes clusters, cloud resources)
• Database administration (e.g., PostgreSQL)
• All configuration files, environment variables, and secrets
• Network and security settings
• Container orchestration and system logs

Deployment managers can also decide to keep audits, backups, and copies of information outside of Texera, which are not covered by Texera’s security model. They operate outside the Texera UI role system and may or may not have a UI user account.

UI Users

Who They Are: Individuals who interact with Texera through the web interface.

Access Level: Application-level access only. UI users work within the Texera platform but do not have access to:

• The underlying infrastructure (servers, Kubernetes cluster)
• Database administration
• System configuration files
• Network and firewall settings
• Container orchestration

Roles: UI users are assigned one of four roles (INACTIVE, RESTRICTED, REGULAR, ADMIN) that control their permissions within the Texera application.

Security Scope: UI users are responsible for:

• Protecting their login credentials
• Managing access to their resources, e.g., datasets and workflows
• Following organizational data security policies

UI User Roles and Privileges

Texera implements four UI user roles with increasing levels of privilege. These roles control what users can do within the Texera web application and do not grant infrastructure-level access.

1. INACTIVE

Users with this role cannot log in to the system or access any resources. This is the default role for new registrations awaiting approval in controlled environments.

2. RESTRICTED

Users with this role cannot log in to the system or access any resources. Unlike INACTIVE users, RESTRICTED accounts typically represent users who previously used Texera but are now inactive and no longer use it. Any resources they created in the past remain in the system but are inaccessible to them. This role is used to preserve historical data while preventing further access.

3. REGULAR

Users with this role can create and manage their own resources (datasets, workflows, computing units). They have full READ and WRITE access to resources they own, and their access to other users’ resources is determined by granted permissions (see Resources section above).

They cannot:

• Access other users’ private resources without granted permissions
• Manage user accounts or change user roles
• Access system configuration, logs, or global settings

This is the standard role for data scientists, analysts, and researchers. Note: REGULAR users can execute arbitrary code within workflows, so this role should only be granted to trusted individuals.

4. ADMIN

Users with this role are application administrators who manage users and resources through the web interface.

They have all REGULAR privileges, plus:

• Manage all UI user accounts (create, modify, and delete users)
• Change user roles
• View user login information.
• Configure application settings available in the web interface

They cannot:

• Access the underlying servers or Kubernetes cluster
• Modify JWT secrets or database passwords
• Configure HTTPS/TLS or network settings
• Access system-level logs or SSH into servers

Note: ADMIN is an application-level role, not an infrastructure administrator. For infrastructure management, deployment manager access is required.

Deployments and Computing Units

Texera can be deployed in several configurations, such as local development, single-node setups, or distributed Kubernetes clusters. For details on supported deployment options and their operational differences, see the deployment guides in our wiki.

Computing Unit Types

Texera executes workflows on computing units. UI users (REGULAR and ADMIN) can execute arbitrary code (e.g., through UDFs written in Python, R, Scala) within computing units as part of their workflows. This code is currently not sandboxed or restricted by Texera. Deployment managers configure which types of computing units are available:

Local Computing Units

Local computing units run as processes on the same machine as the Texera services (single-node deployment).

Security characteristics:

• Suitable for development, testing, and small team use
• All computing units share the same host machine
• No infrastructure-level isolation between users’ workflows
• Deployment managers control all computing resources

Security considerations:

• Users’ workflow code executes on the host machine with limited isolation
• Deployment managers must trust all REGULAR and ADMIN users
• Resource exhaustion by one user can affect all users

Kubernetes Computing Units

Kubernetes computing units run as separate PODs in a Kubernetes cluster. Each computing unit is dynamically created when a user needs it.

Security characteristics:

• Suitable for production environments and multi-tenant deployments
• Each computing unit runs in an isolated Kubernetes pod
• UI users configure resource limits (CPU, memory, GPU) per pod
• Pods can be scheduled across multiple nodes for better resource distribution

Security considerations:

• Better isolation between users compared to local computing units
• Kubernetes provides namespace and pod-level isolation
• Resource limits prevent individual users from consuming excessive resources
• Container security and image scanning should be implemented
• Deployment managers must secure the Kubernetes cluster infrastructure

What is NOT Guaranteed

Texera’s security model does NOT guarantee:

• Protection against malicious code in user workflows (users can execute arbitrary code)
• Strong isolation between workflows in local computing units
• Complete isolation between workflows in Kubernetes computing units within the same namespace
• Protection against infrastructure-level compromises
• Protection against deployment manager misconfigurations
• DDoS protection (requires external infrastructure)
• Compliance with specific regulatory requirements without additional configuration

What is NOT a Security Issue

These are things that we are well aware of, and have been reported to us many times, but we do not class as a security vulnerability. Please do not report them.

Issues not classed as security relevant:

• A lack of DMARC or SPF record on our domains
• “Clickjacking” on our domains
• Directory listings. These are deliberate and do not contain sensitive information
• Systems that disclose the versions of the servers and software we use
• Data that is publically accessible in our Jira bug tracking system

Reporting Security Vulnerabilities

We strongly encourage you to report potential security vulnerabilities to one of our private security mailing lists first, before disclosing them in a public forum.

A list of security contacts for Apache projects is available. If you can’t find a project-specific security e-mail address and you have an undisclosed security vulnerability to report, use the general security address below.

Only use the security contacts to report undisclosed security vulnerabilities in Apache projects and manage the process of fixing such vulnerabilities. We cannot accept regular bug reports or other security-related queries at these addresses. We will ignore mail sent to these addresses that does not relate to an undisclosed security problem in an Apache project.

Also note that the security team handles vulnerabilities in Apache projects, not running ASF services. Send reports of vulnerabilities in ASF services to root@apache.org. (This includes issues with apache.org websites)

The general security mailing list address is: security@apache.org. This is a private mailing list.

Please send one plain-text, unencrypted, email for each vulnerability you are reporting. We may ask you to resubmit your report if you send it as an image, movie, HTML, or PDF attachment when you could as easily describe it with plain text.