Getting started / Reference /
Deployments

Deployments

Overview

Deployments represent the process of releasing new versions of your application to Tapitalee. Each deployment creates a new release from your Docker images, manages the rollout process, and provides rollback capabilities. Deployments ensure zero-downtime updates and maintain application availability during releases.

Purpose and Benefits

  • Zero-Downtime Deployment: Rolling updates without service interruption
  • Version Management: Track and manage application versions over time
  • Rollback Capability: Quickly revert to previous working versions
  • Health Monitoring: Automatic health checks during deployment
  • Audit Trail: Complete history of all deployments and changes
  • Integration Ready: Seamless CI/CD pipeline integration

How Deployments Work

Deployment Process

  1. Image Preparation: Docker image is built or tagged
  2. Process Isolation: When deploying the entire app, a separate deployment is created for each Process
  3. Health Validation: New containers are started and health-checked for each Process independently
  4. Independent Rollout: Each Process deployment proceeds independently, allowing other Processes to continue even if one fails
  5. Old Version Cleanup: Previous version containers are terminated for successfully deployed Processes

Multi-Process Deployment Behavior

When you deploy an entire app (without specifying a specific process), Tapitalee creates individual deployments for each Process in your application. This provides several key benefits:

  • Isolation: Each Process deployment is independent and isolated from others
  • Resilience: If one Process deployment fails, other Processes continue their deployment
  • Partial Success: You can have a mix of successful and failed Process deployments
  • Individual Rollback: Failed Processes automatically rollback to their previous version while successful ones remain on the new version

Example Multi-Process Deployment Flow 

# Deploy entire app with multiple processes
tapit create deploy docker_tag=v1.2.3

This command will:

  1. Create a deployment for the default process (web server)
  2. Create a deployment for the worker process (background jobs)
  3. Create a deployment for the scheduler process (cron jobs)
  4. Each deployment proceeds independently
  5. If worker deployment fails, it rolls back while default and scheduler continue
  6. Final result: Mixed deployment state with some processes on new version, failed process on previous version

AWS Infrastructure

Deployments utilize:

  • ECS Fargate: Container orchestration and rolling updates
  • CloudWatch: Deployment monitoring and logging
  • ECR: Container image storage and versioning

CLI Usage

Create Deployment

Trigger a deployment of the app with the specified image tag

tapit create deploy [-w|--wait] [docker_tag=v123-abc123] [initiator=name] [process=name] [skip_predeploy_steps=true]

Parameters

  • docker_tag: Full docker tag including git hash (e.g., v123-abc123); identifies the exact image pulled from ECR (required)
  • initiator: Name of the person or system triggering the deploy (informational only, recorded in the audit trail)
  • process: Override deploy to only the named process instead of default (all processes)
  • skip_predeploy_steps: Skip pre-deploy steps (true/false)
  • -w|--wait: Wait for deployment to complete before returning

Note: git_hash and tag= (git tag) values associated with a build are recorded for informational and audit purposes only. They are not used to identify or pull the Docker image — only docker_tag determines which image is actually deployed and runs live.

Examples 

# Deploy latest version of all processes
tapit create deploy

# Deploy specific Docker tag
tapit create deploy docker_tag=v1.2.3-abc123

# Deploy with tracking and wait for completion
tapit create deploy initiator=john.doe --wait

# Deploy only web process
tapit create deploy process=web docker_tag=v1.2.3

# CI/CD deployment
tapit create deploy docker_tag=$GITHUB_SHA initiator=github-actions --wait

Show Deployment Details

Show current ECS deployment status including rollout state and running counts

tapit show deploy

List Deployments

List recent deployments for the app

tapit list deploys

Deployment Strategy

Tapitalee uses a rolling deployment strategy by default: new containers are started and health-checked before old containers are terminated, ensuring zero-downtime updates.

Image Management

Building Images

Prepare build arguments and record a build entry before pushing an image to ECR

tapit image build [tag=v123] [docker_tag=v123-abc123] [git_hash=abc123] [initiator=name] [dockerfile=path] [cache=ecr|gha]

Parameters

  • tag: Human-readable version tag, e.g. v123 (informational only, not used to pull the image)
  • docker_tag: Full docker tag including git hash, e.g. v123-abc123 (auto-generated if omitted)
  • git_hash: Git commit hash associated with this build (informational only)
  • initiator: Name of the person or system triggering the build (informational only)
  • dockerfile: Path to the Dockerfile to use, enables Docker build mode (default: ./Dockerfile)
  • cache: Enable layer caching: ecr (ECR registry cache) or gha (GitHub Actions cache)

Examples 

# Build with automatic tagging
tapit image build

# Build with specific version
tapit image build tag=v1.2.3 git_hash=$GITHUB_SHA initiator=github-actions

# Build with custom Dockerfile
tapit image build dockerfile=docker/production.Dockerfile

# Build with ECR cache for faster builds
tapit image build cache=ecr tag=v1.2.3

Image Login

Retrieve Docker credentials for logging into the app’s ECR registry

tapit image login [name=addon_name]

Parameters

  • name: Log into a Public Container Registry add-on instead of the app ECR

Authenticates Docker client with your app’s ECR repository for manual image operations.

Direct Image Deployment

Trigger a deployment after a successful image build

tapit image deploy [tag=v123] [docker_tag=v123-abc123] [git_hash=abc123] [initiator=name] [dockerfile=path] [cache=ecr|gha] [process=name] [skip_predeploy_steps=true]

Parameters

  • tag: Human-readable version tag, auto-detected from git if omitted (informational only)
  • docker_tag: Full docker tag including git hash, e.g. v123-abc123 (auto-generated if omitted)
  • git_hash: Git commit hash associated with this build (informational only)
  • initiator: Name of the person or system triggering the deploy (informational only)
  • dockerfile: Path to a Dockerfile (default: ./Dockerfile if present, otherwise buildpacks)
  • cache: Enable layer caching: ecr (ECR registry cache) or gha (GitHub Actions cache)
  • process: Deploy only the named process instead of all processes
  • skip_predeploy_steps: Skip pre-deploy steps (true/false)

Combines image building and deployment in a single command. Equivalent to running image build followed by create deploy.

Examples 

# Build and deploy in one step
tapit image deploy tag=v1.2.3

# Build and deploy specific process
tapit image deploy tag=v1.2.3 process=web

# Build with GitHub Actions cache and deploy
tapit image deploy tag=v1.2.3 cache=gha

List Images

List Docker images in the app’s ECR repository

tapit list images

List Builds

List recent image builds for the app with their state and docker tags

tapit list builds

Show Image Details

Show details of a specific Docker image in the app’s ECR repository

tapit show image docker_tag=tag_name

Parameters

  • docker_tag: The docker tag to look up (required)

Upload Image Binary

Upload a binary artifact to S3 for binary deployment (requires Binary Deployment add-on)

tapit image upload path tag=value

Arguments

  • path - Local file path of the binary artifact to upload

Parameters

  • tag: Version tag to associate with the uploaded binary (required)

Show ECR Details

Show the ECR repository URI for the app’s Docker images

tapit show ecr

Show Running Service

Show running ECS container instances with availability zone and status details

tapit show service

Show Service Events

Show recent ECS service events for the app

tapit show events [process=process_name]

Parameters

  • process: Show events for a specific named process (default: default process)

Deployment Monitoring

Health Checks

Deployments include comprehensive health monitoring:

  • Container Health: ECS health checks for container startup
  • Load Balancer Health: Target group health validation when a Load Balancer is being used

Rollback Triggers

Automatic rollback occurs when the new deployed version fails to start and stay running.

Multi-Process Failure Handling

When deploying multiple processes:

  • Individual Failure: If one Process fails to deploy, only that Process rolls back to its previous version
  • Other Processes Continue: Successful Process deployments remain on the new version
  • No Global Rollback: There is no automatic rollback of all Processes when one fails
  • Manual Coordination: If you need all Processes on the same version, you must manually deploy the failed Process again or rollback successful ones

Handling Mixed Version States 

# Check current deployment status
tapit show deploy

# If worker process failed but others succeeded:
# Option 1: Fix and redeploy worker
tapit create deploy process=worker docker_tag=v1.2.3

# Option 2: Rollback successful processes to match failed one
tapit create deploy process=default docker_tag=v1.2.2  # previous version
tapit create deploy process=scheduler docker_tag=v1.2.2

Deployment Environments

Environment-Specific Deployments 

# Deploy to specific environments as different app names
tapit -a myapp-staging create deploy docker_tag=v1.2.3-rc1
tapit -a myapp-prod create deploy docker_tag=v1.2.3

Process-Specific Deployment 

# Deploy only web processes
tapit create deploy process=default docker_tag=v1.2.3

# Deploy background workers separately
tapit create deploy process=worker docker_tag=v1.2.3-worker

Troubleshooting Deployments 

# Check deployment status
tapit show deploy

# Check container logs
tapit show logs

Manual Rollback 

# Deploy previous working version
tapit create deploy docker_tag=v1.2.2 --wait