Getting Started with Airbase¶

Welcome to Airbase! This tutorial will guide you through deploying your first application to Airbase, from setup to a live URL.

What you'll learn:

How to install and authenticate the Airbase CLI
How to create your first application
How to deploy to Airbase
How to verify your deployment is live

Time to complete: 15-20 minutes

What is Airbase?

Airbase provides a modern developer experience for public officers to easily and quickly deploy applications to the Government Commercial Cloud (GCC). Think Vercel-like simplicity, with the safety and compliance of the government cloud.

New CLI Available

This guide uses the new Go-based Airbase CLI. If you previously used the npm-based CLI (@airbase/airbase-cli), see the CLI Migration Guide.

Prerequisites¶

Before you begin, you need:

These steps can only be completed via the Airbase web console:

Access Airbase Console
Navigate to: https://go.gov.sg/airbase
Login with TechPass or gov.sg email
Create a Team
Click "Create Team" in the console
Provide a team name
Create a Project
Within your team, create a new project
Provide a project name
Note down the Project Handle in format: team-name/project-name
Example: runtime/demo or myteam/myproject

Important

Keep your project handle ready - you'll need it for deployment!

2. Technical Requirements¶

Docker installed and running locally

Step 1: Install the Airbase CLI¶

Visit the CLI download page:

https://go.gov.sg/airbase-cli

The page will detect your system architecture and provide the appropriate installation command.

Example installation command:

curl -fsSL https://console.airbase.tech.gov.sg/dist/install.sh | sh

Installation Location

The installer will place the binary in one of two locations:

~/.local/bin/airbase (if ~/.local/bin exists)
/usr/local/bin/airbase (if ~/.local/bin doesn't exist)

Verify installation:

Check the CLI version:

airbase -v

Expected output:

Version: v1.0.3
Commit: 0c3a3f4
Build Time: 2026-03-30T14:19:11Z

Verify binary location:

which airbase

Expected output (if installed to ~/.local/bin):

/Users/username/.local/bin/airbase

Or (if installed to /usr/local/bin):

/usr/local/bin/airbase

Installation Issues?

If you get "command not found", the installation directory may not be in your PATH.

If installed to ~/.local/bin:

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc  # or ~/.bashrc
source ~/.zshrc  # or source ~/.bashrc

If installed to /usr/local/bin:

echo 'export PATH="/usr/local/bin:$PATH"' >> ~/.zshrc  # or ~/.bashrc
source ~/.zshrc  # or source ~/.bashrc

Step 2: Authenticate with Airbase¶

Authenticate your CLI with Airbase:

airbase login

Authentication flow:

CLI generates a one-time verification code
Open the provided URL in your browser
Verify the code matches on both CLI and browser
Click "Continue" and "Accept" to authorize
Name your API token (e.g., "my-laptop", "dev-machine")
CLI receives confirmation

Terminal view:

You'll see a verification code like this:

Verification code: ABCD-1234
Please visit: https://console.airbase.tech.gov.sg/auth/...

Browser view:

The browser will show the same code and ask you to confirm.

Your credentials are stored in ~/.airbaserc in your home directory.

Authentication Complete

You're now ready to deploy applications to Airbase!

Step 3: Create Your First Application¶

Let's create a simple Node.js Express application.

3.1 Create Project Directory¶

Important: Directory names must be lowercase with no spaces.

mkdir my-first-app
cd my-first-app

3.2 Create package.json¶

cat > package.json << 'EOF'
{
  "name": "my-first-app",
  "version": "1.0.0",
  "description": "My first Airbase app",
  "main": "index.js",
  "scripts": {
    "start": "node index.js"
  },
  "dependencies": {
    "express": "^4.18.2"
  }
}
EOF

3.3 Create index.js¶

Create a simple Express server with CSP-compliant HTML:

cat > index.js << 'EOF'
const express = require('express');
const app = express();
const PORT = process.env.PORT || 3000;

// JSON API endpoint
app.get('/api', (req, res) => {
  res.json({
    message: 'Hello from Airbase!',
    timestamp: new Date().toISOString(),
    environment: process.env.NODE_ENV || 'development'
  });
});

// HTML page - CSP compliant (no inline scripts)
app.get('/', (req, res) => {
  res.send(`
<!DOCTYPE html>
<html>
<head>
  <title>My First Airbase App</title>
  <style>
    body { font-family: Arial, sans-serif; max-width: 600px; margin: 50px auto; padding: 20px; }
    .card { border: 1px solid #ddd; padding: 20px; border-radius: 8px; }
    button { background: #0066cc; color: white; border: none; padding: 10px 20px; border-radius: 4px; cursor: pointer; }
  </style>
</head>
<body>
  <div class="card">
    <h1>Hello from Airbase!</h1>
    <p>Your first application is running successfully.</p>
    <button id="fetchButton">Fetch API Data</button>
    <pre id="output"></pre>
  </div>
  <script src="/script.js"></script>
</body>
</html>
  `);
});

// Serve external JavaScript file (CSP compliant)
app.get('/script.js', (req, res) => {
  res.type('application/javascript');
  res.send(`
document.getElementById('fetchButton').addEventListener('click', async function() {
  const response = await fetch('/api');
  const data = await response.json();
  document.getElementById('output').textContent = JSON.stringify(data, null, 2);
});
  `);
});

app.get('/health', (req, res) => {
  res.json({ status: 'healthy' });
});

app.listen(PORT, () => {
  console.log(\`Server is running on port \${PORT}\`);
});
EOF

Content Security Policy (CSP)

Airbase enforces strict CSP headers. Notice how this example:

Uses external JavaScript (/script.js) instead of inline <script> tags
Uses addEventListener instead of onclick attributes

This is required for all Airbase applications. Learn more about CSP compliance.

3.4 Create Dockerfile¶

Create a Dockerfile using Airbase-managed base images:

cat > Dockerfile << 'EOF'
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"]
EOF

Key points:

Uses Airbase-managed base images (gdssingapore/airbase:node-22)
Multi-stage build for smaller image size
Runs as non-root user (USER app)
Sets proper file ownership (--chown=app:app)

3.5 Create airbase.json¶

Recommended: Use the interactive configuration tool:

airbase configure

This command will: 1. Show you a list of your available projects 2. Let you select your project 3. Prompt you for port (default: 3000) 4. Ask if you want to restrict network access to specific IP addresses (optional) 5. Create airbase.json automatically

Why use airbase configure?

Using the CLI tool reduces the risk of malformed JSON and ensures all required fields are correctly set.

Instance Type

The airbase configure command does not prompt for instance type. To change from the default nano instance type, edit the airbase.json file manually and add "instanceType": "b.small" (or your desired type).

Alternative: Manual creation

If you prefer to create the file manually:

cat > airbase.json << 'EOF'
{
  "framework": "container",
  "handle": "YOUR-TEAM/YOUR-PROJECT",
  "port": 3000,
  "instanceType": "nano"
}
EOF

Replace Project Handle

Replace YOUR-TEAM/YOUR-PROJECT with your actual project handle from Step 1.

Example: "handle": "runtime/demo"

Configuration fields:

framework: Always "container" for containerized apps
handle: Your project handle in format team-name/project-name
port: Application port (default: 3000)
instanceType: Instance size (e.g., nano, b.small)

Step 4: Build Your Application¶

Build the container image:

airbase build

Command Syntax

The new CLI supports shorter commands. You can also use airbase container build for backwards compatibility.

What happens:

CLI reads your Dockerfile
Builds the container image locally using Docker
Pushes the image to Airbase-managed registry via API

Expected output:

Building container...
✓ Build complete
✓ Image pushed to registry

First Build Takes Longer

The first build downloads base images. Subsequent builds are much faster.

Step 5: Deploy to Airbase¶

Deploy your application to the default (production) environment:

airbase deploy --yes

Command Syntax

The new CLI supports shorter commands. You can also use airbase container deploy --yes for backwards compatibility.

Auto Build-and-Deploy

The new CLI can automatically build before deploying if needed. If you skip Step 4, running airbase deploy --yes will build and deploy in one command.

What happens:

CLI reads airbase.json to identify your project
Sends deployment request to Airbase API
Airbase deploys your container to Kubernetes
Your application becomes accessible at a public URL

Expected output:

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

The --yes flag:

Skips the confirmation prompt
Required for default environment deployment
Recommended for all deployments

Step 6: Verify Your Deployment¶

6.1 Check the URL¶

Open your application URL in a browser:

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

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

Example: If your handle is runtime/demo, your URL is:

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

6.2 Test the Application¶

You should see "Hello from Airbase!" page
Click the "Fetch API Data" button
You should see JSON data displayed

6.3 Check for CSP Issues¶

Open the browser console (F12 or right-click → Inspect):

Navigate to the Console tab
Look for any red error messages
No CSP errors should appear if you followed this tutorial

Deployment Complete!

Congratulations! You've successfully deployed your first application to Airbase.

Next Steps¶

Now that you have a working deployment, you can:

Manage environments: Learn about staging and production environments
Iterate on your app: Use staging for development
Deploy other frameworks:
Node.js apps
Python apps
Static sites
Understand CSP: Write CSP-compliant code
Troubleshoot issues: Common problems and solutions

Try the Examples¶

Check out complete working examples:

Learn More¶

Understand how Airbase works:

Troubleshooting¶

Build Fails¶

Issue: Docker not running

# Check Docker is running
docker ps

Issue: Permission errors in container

Ensure all COPY commands use --chown=app:app
Ensure USER app directive is present

Deployment Fails¶

Issue: Directory name has uppercase letters

Rename directory to all lowercase
Example: MyApp → myapp

Issue: Invalid project handle

Verify your handle in Airbase Console
Format must be team-name/project-name

Application Not Loading¶

Issue: Port mismatch

Verify port in airbase.json matches app's listening port
Default is 3000

Issue: CSP violations (JavaScript not working)

Open browser console and check for CSP errors
Debug CSP violations

Need More Help?¶

See the complete troubleshooting guide.

Summary¶

In this tutorial, you:

✅ Installed and authenticated the Airbase CLI
✅ Created a CSP-compliant Node.js application
✅ Built a container image with proper security (non-root user)
✅ Deployed to Airbase
✅ Verified your live deployment

You're now ready to build and deploy your own applications on Airbase!

Getting Started with Airbase¶

Prerequisites¶

1. Login and Create a Team and Project¶

2. Technical Requirements¶

Step 1: Install the Airbase CLI¶

Step 2: Authenticate with Airbase¶

Step 3: Create Your First Application¶

3.1 Create Project Directory¶

3.2 Create package.json¶

3.3 Create index.js¶

3.4 Create Dockerfile¶

3.5 Create airbase.json¶

Step 4: Build Your Application¶

Step 5: Deploy to Airbase¶

Step 6: Verify Your Deployment¶

6.1 Check the URL¶

6.2 Test the Application¶

6.3 Check for CSP Issues¶

Next Steps¶

Try the Examples¶

Learn More¶

Troubleshooting¶

Build Fails¶

Deployment Fails¶

Application Not Loading¶

Need More Help?¶

Summary¶