Self-Hosting tulpal

Prerequisites

• ✓ Docker is already installed.
• ✓ Docker Compose is installed, too.

Architecture

The setup consists of several containers working together:

• tulpal-portal: The main web application server.
• postgres: The database for storing user data and task history.
• task-fetcher: Background service that syncs tasks from repositories.
• task-executor: The agent that performs the tasks.

Step 1: Create Configuration

Create a directory for your tulpal setup and create a file named docker-compose.yml with the following content:

version: '3.8'

services:
  tulpal-portal:
    image: docker.io/tulpaldocker/tulpal-portal:latest
    ports:
      - "8080:8080"
    environment:
      - DB_DIALECT=postgres
      # Connect to the postgres service.
      # We use the service name 'postgres' as the host.
      - DB_CONNECTION=host=postgres user=postgres password=postgres dbname=tulpal port=5432 sslmode=disable
      # Initial account email (created only if database is empty)
      - INITIAL_ACCOUNT_EMAIL=admin@example.org
    depends_on:
      - postgres
    restart: always

  task-fetcher:
    image: tulpaldocker/tulpal-taskfetcher:latest
    environment:
      - DB_DIALECT=postgres
      - DB_CONNECTION=host=postgres user=postgres password=postgres dbname=tulpal port=5432 sslmode=disable
    depends_on:
      - postgres
    restart: always

  postgres:
    image: postgres:18.1
    environment:
      - POSTGRES_USER=postgres
      - POSTGRES_PASSWORD=postgres
      - POSTGRES_DB=tulpal
    volumes:
      - postgres_data:/var/lib/postgresql
    ports:
      - "5432:5432" # Optional: Expose postgres port if external access is needed
    restart: always

  task-executor:
    image: tulpaldocker/tulpal-taskexec:latest
    environment:
      - PORTAL_URL=http://tulpal-portal:8090
      - DB_DIALECT=postgres
      - DB_CONNECTION=host=postgres user=postgres password=postgres dbname=tulpal port=5432 sslmode=disable
    depends_on:
      - tulpal-portal
      - postgres
    restart: always

volumes:
  postgres_data:

Step 2: Start Services

Run the following command in the directory where you created the docker-compose.yml file:

This will download the necessary images and start the containers in the background.

Step 3: Verification

Once the services are running, you can access the tulpal Portal by opening your browser and navigating to:

You should see the tulpal login screen or dashboard.

Configuration & Management

Initial User

When the application starts with an empty database, it creates an initial user account. The email for this account is defined by the INITIAL_ACCOUNT_EMAIL environment variable in docker-compose.yml (default: admin@example.org).

You can log in using this email address directly.

Database Credentials

The default configuration uses postgres/postgres. To change these, update the environment variables in docker-compose.yml for all services connecting to the database.

Stopping Services

Viewing Logs

Data Persistence

Database data is persisted in a Docker volume named postgres_data. To reset the database completely (caution: this deletes all data), run:

Next Steps

Now that you have tulpal up and running, learn how to create your first project and start assigning tasks.