Deploy Pre-Built Docker Image¶

Example: Deploying a pre-built Docker image to Airbase

This example demonstrates how to deploy an application using a pre-built Docker image, without building from source. This approach is useful when you have images from CI/CD pipelines, external registries, or want to quickly deploy a demo application.

What You'll Learn¶

• Pulling Docker images for deployment
• Deploying images to Airbase using CLI
• Deploying to different environments
• Verifying successful deployment

Prerequisites¶

Completed setup: - ✅ Signed up for Airbase account at console.airbase.tech.gov.sg - ✅ Created a team and project in Console - ✅ Installed Airbase CLI: sudo npm install --global @airbase/airbase-cli@containers - ✅ Logged in: airbase login - ✅ Docker installed and running

What you'll need: - Team handle (e.g., demo) - Project handle (e.g., demo-days) - Combined as: demo/demo-days

Step 1: Pull the Pre-Built Image¶

Pull the demo application image from the Airbase registry:

docker pull --platform linux/amd64 gdssingapore/airbase:demo-days

Why --platform linux/amd64? Airbase only supports AMD64 (x86_64) architecture. This flag ensures you pull the correct image, especially important on Apple Silicon (M1/M2/M3) Macs.

Expected output:

demo-days: Pulling from gdssingapore/airbase
Digest: sha256:e99fe672b29b1ee848ff162f6ae7303ace7c523ae6792f3e443f16d783b91eac
Status: Image is up to date for gdssingapore/airbase:demo-days
docker.io/gdssingapore/airbase:demo-days

Verify the image:

docker images | grep demo-days

You should see:

gdssingapore/airbase   demo-days   <image-id>   <time>   <size>

Step 2: Deploy to Production¶

Deploy the image to your Airbase project:

airbase container deploy --project TEAM/PROJECT --image gdssingapore/airbase:demo-days

Replace with your handles:

airbase container deploy --project demo/demo-days --image gdssingapore/airbase:demo-days

Interactive confirmation:

? Deploy gdssingapore/airbase:demo-days to days in default (production) (demo/demo-days:default) Yes

Type Yes and press Enter.

Deployment output:

Deployed days in default (demo/demo-days:default)
Visit https://demo-days.app.tc1.airbase.sg

Step 3: Verify Deployment¶

Open the URL in your browser:

https://demo-days.app.tc1.airbase.sg

Check deployment status:

airbase container list

Expected output:

Environment  URL
-----------  ----------------------------------------
production   https://demo-days.app.tc1.airbase.sg

View application logs: - Open Airbase Console - Navigate to your project → Logs - Select production environment

Deploying to Staging¶

To deploy the same image to a staging environment:

airbase container deploy --project demo/demo-days --image gdssingapore/airbase:demo-days staging

Output:

? Deploy gdssingapore/airbase:demo-days to days in staging (demo/demo-days:staging) Yes
Deployed days in staging (demo/demo-days:staging)
Visit https://staging--demo-days.app.tc1.airbase.sg

Verify staging deployment:

airbase container list

Output:

Environment  URL
-----------  ------------------------------------------------
production   https://demo-days.app.tc1.airbase.sg
staging      https://staging--demo-days.app.tc1.airbase.sg

Deploying Custom Images¶

From Docker Hub¶

Example: Deploy nginx image:

# Pull image
docker pull --platform linux/amd64 nginx:alpine

# Tag for deployment (optional but recommended)
docker tag nginx:alpine my-nginx:v1

# Deploy
airbase container deploy --project myteam/mynginx --image my-nginx:v1

From Private Registry¶

Example: Deploy from AWS ECR:

1. Authenticate with ECR:

   aws ecr get-login-password --region us-west-2 | \
     docker login --username AWS --password-stdin 123456789.dkr.ecr.us-west-2.amazonaws.com
   

2. Pull image:

   docker pull --platform linux/amd64 123456789.dkr.ecr.us-west-2.amazonaws.com/my-app:v1.0
   

3. Tag for local deployment:

   docker tag 123456789.dkr.ecr.us-west-2.amazonaws.com/my-app:v1.0 my-app:v1.0
   

4. Deploy:

   airbase container deploy --project myteam/myapp --image my-app:v1.0
   

From GitLab Container Registry (SGTS)¶

Example: Deploy from SGTS GitLab:

1. Authenticate:

   docker login sgts.gitlab-dedicated.com:5050
   

2. Username: Your GitLab username

3. Password: GitLab Personal Access Token

4. Pull image:

   docker pull --platform linux/amd64 \
     sgts.gitlab-dedicated.com:5050/mygroup/myproject/myapp:v1.0
   

5. Tag locally:

   docker tag \
     sgts.gitlab-dedicated.com:5050/mygroup/myproject/myapp:v1.0 \
     myapp:v1.0
   

6. Deploy:

   airbase container deploy --project myteam/myapp --image myapp:v1.0
   

Deploying with CI/CD¶

GitLab CI Example¶

Build in CI, deploy pre-built image:

stages:
  - build
  - deploy

build:
  stage: build
  script:
    - docker build --platform linux/amd64 -t my-app:${CI_COMMIT_SHA} .
    - docker tag my-app:${CI_COMMIT_SHA} my-app:latest

deploy:
  stage: deploy
  script:
    - docker pull my-app:${CI_COMMIT_SHA}
    - airbase container deploy --project myteam/myapp --image my-app:${CI_COMMIT_SHA} --yes
  only:
    - main

GitHub Actions Example¶

name: Deploy to Airbase

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - name: Build Docker image
        run: docker build --platform linux/amd64 -t my-app:${{ github.sha }} .

      - name: Deploy to Airbase
        run: |
          npm install -g @airbase/airbase-cli@containers
          echo "${{ secrets.AIRBASE_RC }}" > ~/.airbaserc
          airbase container deploy --project myteam/myapp --image my-app:${{ github.sha }} --yes

Advanced: Multi-Stage Deployment¶

Deploy to staging, test, then production:

# Deploy to staging
airbase container deploy --project demo/myapp --image myapp:v2.0 staging --yes

# Run tests against staging
curl https://staging--myapp.app.tc1.airbase.sg/health

# If tests pass, deploy to production
airbase container deploy --project demo/myapp --image myapp:v2.0 production --yes

Updating Deployments¶

Deploy a new version:

1. Pull new image:

   docker pull --platform linux/amd64 gdssingapore/airbase:demo-days-v2
   

2. Deploy update:

   airbase container deploy --project demo/demo-days --image gdssingapore/airbase:demo-days-v2
   

3. Verify update:

4. Check logs in Airbase Console for production environment
5. Verify new version is running

Airbase automatically: - Stops the old container - Starts the new container - Routes traffic to the new deployment - Typically takes 10-30 seconds

Troubleshooting¶

"Image not found" Error¶

Problem:

Error: Failed to find image gdssingapore/airbase:demo-days

Solutions: 1. Verify image exists locally:

docker images | grep demo-days

1. Pull the image again:

   docker pull --platform linux/amd64 gdssingapore/airbase:demo-days
   

2. Check image name spelling (case-sensitive)

"Wrong platform" Warning¶

Problem:

WARNING: The requested image's platform (linux/arm64) does not match the detected host platform (linux/amd64)

Solution: Always use --platform linux/amd64 when pulling:

docker pull --platform linux/amd64 <image-name>

Or build with platform flag:

docker build --platform linux/amd64 -t my-app .

Application Not Accessible¶

Problem: URL returns 503 or 404

Solutions:

1. Check deployment status:

   airbase container list
   

2. View logs for errors:

3. Check logs in Airbase Console for production environment

4. Look for startup errors or crashes

5. Verify image runs locally:

   docker run -p 3000:3000 -e PORT=3000 gdssingapore/airbase:demo-days
   

6. Check if app binds to PORT:

7. Ensure application reads $PORT environment variable
8. Default port should be 3000

Permission Denied Errors¶

Problem: "permission denied" in container logs

Solution: Ensure your Dockerfile uses non-root user:

USER app

Custom images must use UID 999:

RUN useradd -u 999 -m app
USER app

Key Takeaways¶

✅ Always use --platform linux/amd64 when pulling images for Airbase

✅ Use --project and --image flags to deploy pre-built images

✅ Deploy to staging first for testing before production

✅ Check logs immediately after deployment to catch issues early

✅ Images can come from any registry (Docker Hub, ECR, GitLab, etc.)

Next Steps¶

After deploying a pre-built image:

1. Learn to build from source:

2. See: Build and Deploy

3. Explore starter templates:

4. See: Starter Templates

5. Set up CI/CD:

6. See: GitLab CI/CD Integration

7. Customize your deployment:

8. See: Environment Variables
9. See: Manage Environments

See Also¶

• How-To: Build and Deploy - Build from source
• How-To: Manage Environments - Environment management
• Reference: CLI Commands - Full CLI reference
• Examples: Node.js Express - Build and deploy Node.js app