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

Image Preparation: Docker image is built or tagged
Process Isolation: When deploying the entire app, a separate deployment is created for each Process
Health Validation: New containers are started and health-checked for each Process independently
Independent Rollout: Each Process deployment proceeds independently, allowing other Processes to continue even if one fails
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:

Create a deployment for the default process (web server)
Create a deployment for the worker process (background jobs)
Create a deployment for the scheduler process (cron jobs)
Each deployment proceeds independently
If worker deployment fails, it rolls back while default and scheduler continue
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

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

Parameters

docker_tag: (Required) The Docker image tag to deploy. This is the tag applied to the container image at build time and is the identifier used to pull the exact image from ECR and run it in ECS. Every container that ends up running live in your app is identified and pulled by this tag.
--wait: Wait for deployment completion before returning
initiator: Name of person/system initiating the deployment (informational only — recorded in the audit trail)
process: Deploy only a specific process instead of all processes

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

tapit  show deploy

Shows details of the most recent deployment including status, timing, and any issues.

List Deployments

tapit  list deploys

Shows deployment history with status, timing, and metadata.

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

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

Parameters

docker_tag: (Required for reproducible deployments) The tag applied to the container image in ECR. This is the value you will pass to create deploy to run this exact image. If omitted, one is auto-generated.
tag: Human-readable git tag or version label (e.g. v1.2.3). Informational only — not used to identify or pull the image.
git_hash: Git commit hash. Informational only — recorded for traceability but not used to pull the image.
initiator: Person/system building the image. Informational only.
dockerfile: Path to Dockerfile (default: ./Dockerfile)
cache: Build cache strategy (ecr or gha)

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

tapit  image login

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

Direct Image Deployment

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

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

Optional Parameters

tag: Human-readable version tag. Auto-detected from git if omitted. Recorded for informational purposes only.
docker_tag: The unique image tag carried through from build → release → deployment. Auto-generated if omitted.
git_hash: Git commit hash. Recorded for informational purposes.
initiator: Name to record as the initiator.
dockerfile: Path to a Dockerfile. Defaults to ./Dockerfile if present, otherwise buildpacks.
cache: Build cache strategy. ecr uses the app’s ECR for layer caching — most efficient when building in the same AWS region as the app. gha uses GitHub Actions cache — ideal for CI builds on GitHub Actions.
process: Deploy only the specified process. Deploys all processes by default.

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

tapit  list images

Shows available Docker images in your ECR repository.

List Builds

tapit  list builds

Shows the history of image build operations for your application.

Show Image Details

tapit  show image docker_tag=tag_name

Shows details about a specific Docker image including size and timestamps.

Upload Image Binary

tapit  image upload path tag=value

Uploads a pre-built binary artifact directly to your app’s storage. Requires the binary deployment feature to be enabled.

Required Parameters

path: Local path to the binary file to upload
tag: Tag to associate with the uploaded binary

Show ECR Details

tapit  show ecr

Shows details about your application’s ECR (Elastic Container Registry) repository, including the repository URI for pushing images.

Show Running Service

tapit  show service

Displays the currently running containers in your application’s ECS service, including process names, container status, deployment information, and availability zones.

Show Service Events

tapit  show events [process=process_name]

Shows recent ECS service events for a process (default: default process). Useful for debugging deployment and container issues.

Optional Parameters

process: Process name to show events for (default: default)

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

Apps Releases