Getting started / Reference /
Tasks

Tasks

Overview

Tasks are one-time container executions for running background jobs, database migrations, administrative scripts, interactive console sessions, and other ad-hoc operations. Unlike processes (which run continuously), tasks run to completion and then terminate.

Purpose and Benefits

  • Isolated Execution: Each task runs in its own container with a clean environment
  • Resource Control: Configurable CPU, memory, and execution time limits
  • Interactive Sessions: Support for live interactive console sessions (e.g. bash, rails console)
  • Audit Trail: Complete history of all task executions and their logs
  • Flexible Execution: Use your app’s Docker image, the Tapitalee utility image, or any custom image

CLI Usage

Create Background Task

Run a one-off non-interactive background task in an ephemeral container with the given command

tapit create task 'background command here' [-w|--wait] [memory|cpu|docker_tag|image|max_hours|initiated_by|ephemeral_storage_gb]=value

Arguments

  • ‘background command here’ - The command to run in the container

Parameters

  • memory: Memory allocation in GB (default: 2)
  • cpu: CPU allocation in vCPUs (default: 1)
  • docker_tag: Docker image tag to use (optional, overrides latest deployed)
  • image: Custom Docker image URI to use (optional, overrides docker_tag)
  • max_hours: Maximum runtime in hours before the task is killed (default: 48)
  • initiated_by: Name of the person or system that initiated the task
  • ephemeral_storage_gb: Ephemeral storage size in GB (default: 20)
  • -w|--wait: Wait for the task to finish and stream its exit status

Examples 

# Run a database migration
tapit create task 'rails db:migrate'

# Run with explicit resource allocation
tapit create task 'python scripts/process_data.py' memory=4.0 cpu=2.0

# Run and wait for completion
tapit create task 'bundle exec rake data:import' --wait

# Run with a specific image tag
tapit create task 'rails db:seed' docker_tag=v1.2.3

# Run with a time limit
tapit create task 'python long_running_job.py' max_hours=6

# Run a command using a public Ubuntu image
tapit create task 'apt-get install -y curl && curl https://example.com/report' image=ubuntu:24.04

Run Interactive Console

Launch an interactive CLI-based terminal console session inside an ephemeral container

tapit run 'bash' [local|memory|cpu|docker_tag|image|max_hours|ephemeral_storage_gb]=value

Arguments

  • ‘bash’ - The shell or command to open in the container

Parameters

  • local: Run the session locally instead of in the cloud (local dev only)
  • memory: Memory allocation in GB
  • cpu: CPU allocation in vCPUs
  • docker_tag: Docker image tag to use
  • image: Custom Docker image URI to use
  • max_hours: Maximum session duration in hours
  • ephemeral_storage_gb: Ephemeral storage size in GB (default: 20)

Examples 

# Open a bash shell
tapit run 'bash'

# Open a Rails console
tapit run 'rails console'

# Open a Python interactive session
tapit run 'python'

# Open console with more memory
tapit run 'bash' memory=2.0

Show Task Details

Show details and logs for a specific task

tapit show task task=<task_name>

Parameters

  • task: Name of the task to show (required)

List Tasks

List background tasks for the app with their state and exit reason

tapit list tasks [-all] [from=iso8601] [to=iso8601] [interval=1h|4h|12h|24h|3d|7d|14d] [limit=n]

Parameters

  • from: Start of the time range with -all (ISO8601 timestamp)
  • to: End of the time range with -all (ISO8601 timestamp, defaults to now)
  • interval: Named interval instead of from/to with -all, eg. 4h, 24h, 7d
  • limit: Maximum number of tasks to list (default 50)
  • -all: Include already completed historic tasks. Without this means only currently running tasks are shown.

Delete Task

Stop and delete a running or completed task

tapit delete task task=task_name

Parameters

  • task: Name of the task to delete (required)

View Task Logs

Task logs can be viewed via the logs command:

# View logs for a specific task
tapit show logs task=<task_id>

Task Types

Background Tasks

Created with create task. Run asynchronously to completion. Useful for:

  • Database migrations
  • Data import/export scripts
  • Batch processing jobs
  • One-time administrative operations

Console Sessions

Created with run. Provide an interactive terminal session. Useful for:

  • Debugging and investigation
  • Running application consoles (Rails, Django shell, etc.)
  • Manual data fixes
  • System inspection

Resource Defaults

Tasks inherit default resource settings from your app configuration. You can override these per-task:

  • Memory: Default from app settings (typically 0.5 GB)
  • CPU: Default from app settings (typically 0.25 vCPUs)
  • Max Hours: No limit by default

The Utility Image

Tapitalee provides a ready-made utility image for running tasks and console sessions. It is an Ubuntu-based container image preloaded with the tools most commonly needed to inspect and maintain an app’s data, so you don’t need to install them in your own app image.

Included Tools

Tool Purpose
psql, pg_dump, pg_restore PostgreSQL client, backup and restore
mysql, mysqldump, mysqlsh MySQL client, backup and restore
redis-cli Redis / Valkey client
redisync Copies all keys (with TTLs) from one Redis to another, supports redis:// and rediss:// URLs
dbconsole Opens an interactive console for a database URL, picking the right client for PostgreSQL, MySQL or Redis
dbtop Shows the top currently running queries on a database
aws The AWS CLI
s5cmd Fast parallel S3 copy/sync tool
tapit The Tapitalee CLI

As it is based on Ubuntu, other packages can be installed on the fly with apt-get if needed.

No App Image Required

The utility image does not depend on your app’s own Docker image, so it can be used before you have built or deployed any app images at all. This makes it useful for setting up or importing data into databases before the first deployment, or for apps whose images are minimal and lack a shell or debugging tools.

Access to Your App’s Data

Tasks using the utility image run inside your app’s VPC with the same environment variables, secrets and IAM task role as your app. Everything your app can reach, the utility image can reach too:

  • Add-on connection variables like DATABASE_URL and REDIS_URL are set, and the databases are reachable on the network.
  • S3 buckets and other AWS resources attached to the app are accessible via the AWS CLI without extra credentials.
  • If the Tapitalee CLI add-on is attached, TAPIT_TOKEN is set so tapit works without logging in.

This makes it the natural place to perform database maintenance: running ad-hoc queries, taking and restoring dumps, copying data between databases, and investigating slow queries.

Using the Utility Image

Pass image=utility (or image=utilitycontainer) to run or create task. In the web UI, click Quick utility console on the app’s Tasks page to open a browser console using the utility image. Database add-on pages also offer shortcuts to open a dbconsole or dbtop session directly.

Examples 

# Open an interactive shell in the utility image
tapit run bash image=utility

# Open an interactive database console
tapit run 'dbconsole $DATABASE_URL' image=utility

# Show the top running queries
tapit run 'dbtop $DATABASE_URL' image=utility

# Dump a PostgreSQL database to an S3 bucket add-on
tapit create task 'pg_dump -Fc "$DATABASE_URL" | aws s3 cp - "s3://$S3_BUCKET/backup.dump"' image=utility --wait

# Restore a PostgreSQL dump from S3
tapit create task 'aws s3 cp "s3://$S3_BUCKET/backup.dump" - | pg_restore --no-owner -d "$DATABASE_URL"' image=utility --wait

# Copy all keys from an external Redis into the app's Redis add-on
tapit create task 'redisync -from "$OLD_REDIS_URL" -to "$REDIS_URL"' image=utility --wait

Environment variables in commands are expanded inside the container, so quote them with single quotes on your local shell as above.

Copying Files Into and Out of Containers

You can copy a file into a container like this:

( echo 'cat > /path/to/file' ; cat local_filename ) | tapit run bash image=utility

And out again:

tapit run 'cat /path/to/file' image=utility > local_filename

This could be useful for eg. copying small files quickly into and out of an EFS mount. It is not suited to large files.

Best Practices

  • Use max_hours for long-running jobs to avoid runaway tasks
  • Use initiated_by to track who launched tasks in audit logs
  • Check task logs promptly after completion for error detection, or use –wait