Build and Deploy Applications¶

Learn how to build container images and deploy them to Airbase.

Prerequisites¶

Before building and deploying:

• Airbase CLI installed and authenticated
• Docker installed and running
• Project has a Dockerfile
• Project has an airbase.json configuration file
• Directory name is lowercase with no spaces

Quick Reference¶

# Build container image
airbase container build

# Deploy to default environment (production)
airbase container deploy --yes

# Deploy to named environment (e.g., staging)
airbase container deploy --yes staging

Building Your Application¶

Step 1: Create a Dockerfile¶

Your Dockerfile must follow Airbase platform constraints:

1. Run as non-root user (USER app with UID 999)
2. Set proper file ownership (--chown=app:app)
3. Listen on the port specified in airbase.json

Recommended: Use Airbase-managed base images for a smoother deployment experience on our platform

Example for Node.js:

FROM gdssingapore/airbase:node-22-builder AS builder
WORKDIR /app
COPY package.json package-lock.json* ./
RUN npm install

FROM gdssingapore/airbase:node-22
WORKDIR /app
COPY --from=builder --chown=app:app /app/node_modules ./node_modules
COPY --chown=app:app package.json ./
COPY --chown=app:app index.js ./
USER app
CMD ["node", "index.js"]

Example for Python:

FROM gdssingapore/airbase:python-3.13
ENV PYTHONUNBUFFERED=TRUE
COPY --chown=app:app requirements.txt ./
RUN pip install -r requirements.txt
COPY --chown=app:app . ./
USER app
CMD ["bash", "-c", "python app.py"]

See Dockerfile Requirements for complete specifications.

Step 2: Run the Build Command¶

airbase container build

What happens:

1. CLI reads your Dockerfile from the current directory
2. Builds the container image using Docker locally
3. Tags the image appropriately
4. Pushes the image to Airbase-managed registry via API

Expected output:

Building container...
[+] Building 45.2s (12/12) FINISHED
 => [internal] load build definition from Dockerfile
 => => transferring dockerfile: 326B
 => [internal] load .dockerignore
 => ...
✓ Build complete
✓ Image pushed to registry

Build time:

• First build: 2-5 minutes (downloads base images)
• Subsequent builds: 30 seconds - 2 minutes (uses cache)

Troubleshooting Build Issues¶

Issue: Docker not running

Cannot connect to the Docker daemon...

Solution:

# Check Docker status
docker ps

# Start Docker Desktop (macOS/Windows)
# Or start Docker service (Linux)
sudo systemctl start docker

Issue: Permission errors in container

Permission denied

Solution:

• Ensure all COPY commands use --chown=app:app
• Ensure USER app directive is present
• Files should be owned by the app user, not root

Issue: Build fails to find files

COPY failed: file not found

Solution:

• Verify files exist in current directory
• Check file paths in Dockerfile
• Review .dockerignore (if present) - files may be excluded

Deploying Your Application¶

Step 1: Create airbase.json¶

Recommended: Use the CLI configuration tool:

airbase configure

This interactive tool will guide you through: - Selecting your project from available projects - Setting the application port (default: 3000) - Optionally configuring IP address whitelisting

Note: To set a specific instance type (e.g., b.small), edit the generated airbase.json file manually after running airbase configure.

Alternative: Create manually

If you prefer to create the file manually:

{
  "framework": "container",
  "handle": "team-name/project-name",
  "port": 3000,
  "instanceType": "nano"
}

Replace team-name/project-name with your actual project handle from Airbase Console.

See airbase.json Reference for all configuration options.

Step 2: Deploy to Default Environment¶

Deploy to the default (production) environment:

airbase container deploy --yes

What happens:

1. CLI reads airbase.json to identify your project
2. Sends deployment request to Airbase API
3. Airbase pulls your container image from the registry
4. Deploys the container to Kubernetes
5. Your application becomes accessible at a public URL

Expected output:

Deploying to default environment...
✓ Deployment successful
✓ Application is live at: https://project-name.app.tc1.airbase.sg

Deployment time: 30 seconds - 2 minutes

Step 3: Verify Deployment¶

Open your application URL:

https://YOUR-PROJECT-NAME.app.tc1.airbase.sg

Replace YOUR-PROJECT-NAME with your project name (the part after the slash in your handle).

Example: Handle runtime/demo → URL https://demo.app.tc1.airbase.sg

Check browser console for CSP violations:

1. Press F12 to open developer tools
2. Navigate to Console tab
3. Look for red errors mentioning "Content Security Policy"
4. If found, see Troubleshoot CSP

Deploy Command Options¶

--yes Flag¶

Skips the confirmation prompt (recommended for all deployments).

airbase container deploy --yes

Why use --yes:

• Default environment deployment requires --yes (prompt defaults to "N")
• Named environments don't require it, but using it is more consistent
• Enables non-interactive deployment (CI/CD)

Named Environments¶

Deploy to environments other than production:

# Deploy to staging
airbase container deploy --yes staging

# Deploy to development
airbase container deploy --yes development

# Deploy to feature branch
airbase container deploy --yes feature-user-auth

See Manage Environments for detailed environment management.

Other Options¶

# Deploy specific image
airbase container deploy --yes --image my-image:v1.2.3

# Override project handle
airbase container deploy --yes --project team/project

# Override port
airbase container deploy --yes --port 8080

# Output deployment URL to file
airbase container deploy --yes --output deploy-url.txt

See CLI Commands Reference for complete options.

Deployment Workflow Patterns¶

Pattern 1: Direct to Production¶

Use when: Small changes, high confidence

# Make changes to code
# Build and deploy directly
airbase container build
airbase container deploy --yes

Pattern 2: Test in Staging First¶

Use when: Larger changes, want to verify first

# Make changes to code
# Deploy to staging
airbase container build
airbase container deploy --yes staging

# Test at https://staging--project-name.app.tc1.airbase.sg
# If good, deploy to production
airbase container deploy --yes

See Iterative Development for complete staging workflow.

Pattern 3: Multiple Environments¶

Use when: Complex features, team collaboration

# Deploy to feature environment
airbase container build
airbase container deploy --yes feature-auth

# Deploy to development
airbase container deploy --yes development

# Deploy to staging
airbase container deploy --yes staging

# Finally, deploy to production
airbase container deploy --yes

Environment Variables¶

Deploy with environment-specific configuration:

Create environment files:

.env                # For default/production
.env.staging        # For staging
.env.development    # For development

Example .env file:

PORT=3000
DATABASE_URL=postgresql://prod-db.example.com/myapp
API_KEY=prod-key-123
NODE_ENV=production

On deployment:

• CLI reads the appropriate .env file
• Variables are sent to Airbase (not baked into image)
• Variables are injected at runtime

See Set Environment Variables for complete guide.

Redeployment¶

Update Existing Deployment¶

To update an existing deployment:

# Make code changes
# Rebuild and redeploy
airbase container build
airbase container deploy --yes

The new container replaces the old one. No downtime during deployment.

Deploy Without Rebuilding¶

If you've already built an image and just want to redeploy:

# Just redeploy (uses last built image)
airbase container deploy --yes

Deploy to Multiple Environments¶

After building once, deploy to multiple environments:

# Build once
airbase container build

# Deploy to multiple environments
airbase container deploy --yes staging
airbase container deploy --yes development
airbase container deploy --yes production

Best Practices¶

✅ Do¶

• Always use --yes flag for consistent, non-interactive deployments
• Test CSP compliance before deploying (check browser console)
• Use staging environment for testing changes
• Keep Dockerfiles simple and well-documented
• Use multi-stage builds to minimize image size
• Set proper file ownership (--chown=app:app)
• Run as non-root user (USER app)

❌ Don't¶

• Don't skip the build step - always rebuild after code changes
• Don't commit secrets - use environment variables
• Don't use inline scripts - violates CSP (learn more)
• Don't use uppercase in directory names
• Don't forget to test after deployment

Common Issues¶

Issue: Deployment Fails with "Invalid Handle"¶

Solution: Verify your project handle in airbase.json matches what's in Airbase Console.

Issue: Application Not Accessible¶

Possible causes:

1. Port mismatch: port in airbase.json must match app's listening port
2. App not starting: Check logs in Airbase Console
3. Wrong URL: Use project-name (not team name) in URL

Issue: Build Works But Deploy Fails¶

Check:

• airbase.json exists and is valid JSON
• Project handle is correct
• You're authenticated (airbase login)

Issue: CSP Violations After Deployment¶

Solution:

1. Open browser console (F12)
2. Look for CSP errors
3. Follow Troubleshoot CSP guide

Next Steps¶

• Manage environments: Create and manage staging/production environments
• Set environment variables: Configure app settings per environment
• Iterate efficiently: Use staging for development workflow
• Undeploy: Remove applications from Airbase

See Also¶

• Tutorial: Getting Started Guide
• Reference: CLI Commands
• Reference: Dockerfile Requirements
• Reference: airbase.json Configuration
• Explanation: How Deployment Works

Summary¶

Build workflow:

1. Create Dockerfile (with non-root user, proper ownership)
2. Run airbase container build
3. Image is built and pushed to registry

Deploy workflow:

1. Create airbase.json (with project handle)
2. Run airbase container deploy --yes
3. Application is deployed and accessible via URL

Remember: Always test for CSP compliance after deployment!