Quick Start

CLI Installation

Download Binary (Recommended)

# macOS/Linux
curl -sSL https://deployaja.id/setup.sh | bash

# Windows
iwr -useb https://deployaja.id/setup.bat | iex

Build from Source

git clone https://github.com/deployaja/deployaja-cli.git
cd deployaja-cli
go build -o aja main.go

Using Docker

docker pull ghcr.io/deployaja/deployaja-cli/aja

Deploy Your Own App

# 1. Initialize configuration
$ aja init

# 2. Edit deployaja.yaml for your app
$ vim deployaja.yaml

# 3. Login to DeployAja
$ aja login

# 4. See costs plan
$ aja plan

# 5. Deploy
$ aja deploy

# Alternative: Generate config with AI
$ aja gen "create a nodejs api with postgresql database"

# Validate configuration
$ aja validate

# Monitor via CLI or Web Interface
$ aja status
# Web: https://deployaja.id/admin

GitHub Actions Integration

Use the official DeployAja GitHub Action for automated deployments:

See a GitHub Actions demo using DeployAja →

Quick Start

name: Deploy with DeployAja
on:
  push:
    branches: [ main ]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Deploy Application
        uses: deployaja/deployaja-cli@v1
        with:
          command: 'deploy'
          api-token: ${{ secrets.DEPLOYAJA_API_TOKEN }}          
      

Action Inputs

InputDescriptionRequiredDefault
commandDeployAja command to executeYesstatus
api-tokenDeployAja API token for authenticationNo-
config-filePath to DeployAja configuration fileNo./deployaja.yaml
environmentTarget environment for deploymentNoproduction
project-nameName of the project to deployNo-
additional-argsAdditional arguments to pass to the CLINo-

Action Outputs

OutputDescription
deployment-idID of the created deployment
deployment-urlURL of the deployed application
statusStatus of the deployment operation

Configuration Example

deployaja.yaml

# Application metadata
name: "arjuna-23-app"              # Required: Application name
description: "My awesome app"       # Optional: Description

 Container configuration
container:
  image: "node:18-alpine"          # Required: Docker image
  port: 3000                       # Required: Container port

# Resource requirements
resources:
  cpu: "500m"                      # CPU request (millicores)
  memory: "1Gi"                    # Memory request
  replicas: 2                      # Number of instances

# Dependencies (managed services)
dependencies:
  - name: "postgres"
    type: "POSTGRESQL"
    version: "15"
    storage_size: "2Gi"

# Environment variables
env:
  - name: "NODE_ENV"
    value: "production"
  - name: "LOG_LEVEL"
    value: "info"

For complete configuration reference, see our detailed documentation →

Commands

Core Commands

CommandDescription
aja initCreate deployaja.yaml configuration with random Wayang-inspired name
aja gen PROMPTGenerate deployment configuration using AI based on natural language prompt
aja validateValidate configuration file
aja planShow deployment plan and costs
aja deployDeploy application
aja statusCheck deployment health and status
aja describe NAMEDescribe deployment pod details (status, containers, events, etc.)
aja logs NAMEView application logs

Management Commands

CommandDescription
aja env [edit|set|get]Manage environment variables
aja restart NAMERestart deployment by recreating pods
aja drop NAMEDelete deployment
aja rollback NAMERollback to previous version

Utility Commands

CommandDescription
aja deps [instance]List available dependencies and versions
aja loginAuthenticate with platform using browser OAuth
aja configShow configuration
aja search QUERYSearch for apps in the marketplace
aja listList all marketplace apps with filtering and pagination
aja install APPNAMEInstall an app from the marketplace
aja publishPublish your app to the marketplace
aja upgradeUpgrade CLI to the latest version
aja versionShow CLI version

Command Examples

# Deploy with configuration overrides
aja deploy --set container.image=nginx:alpine --set resources.replicas=3

# Deploy with custom config file
aja deploy --file my-custom-config.yaml

# Deploy with custom name override
aja deploy --name my-production-app

# Dry run deployment
aja deploy --dry-run

# Follow logs in real-time
aja logs my-app --follow

# Follow logs with specific tail count
aja logs my-app --tail 50 -f

# Check all deployments
aja status

# Describe pod details with events
aja describe my-app

# List dependencies with pricing
aja deps --type database

# Get specific dependency instance details
aja deps my-postgres-instance

# Edit environment variables in vim
aja env edit

# Set environment variable
aja env set DEBUG=true

# Get all environment variables
aja env get

# Get specific environment variable
aja env get DEBUG

# Restart deployment (recreates all pods)
aja restart my-app

# Generate configuration with AI
aja gen "create a nodejs api with postgresql database"
aja gen "docker configuration for wordpress with mysql"

# Search for apps in marketplace
aja search wordpress
aja search "node.js api"

# List all marketplace apps with filtering
aja list
aja list --category cms --sort-by downloads --sort-order desc
aja list --author "WordPress.org" --page 2 --limit 10
aja list --query "node.js" --category api

# Install app from marketplace
aja install wordpress
aja install react-app --domain myapp.example.com --name my-react-app

# Publish your app to marketplace
aja publish

# Upgrade CLI to latest version
aja upgrade

Marketplace

The Aja marketplace provides pre-configured applications that you can deploy with a single command.

Searching Apps

# Search by name
aja search wordpress

# Search by description
aja search "node.js api"

# Search by category
aja search "blog"
Searching for: wordpress

Found 3 apps

1 WordPress
   A popular content management system
   Category: CMS
   Author: WordPress.org
   Version: 6.4
   Downloads: 15420
   Rating: 4.8/5.0
   Tags: cms, blog, php, mysql

Use 'aja install <app-name>' to install an app

Available App Categories

  • CMS: Content Management Systems (WordPress, Drupal, etc.)
  • E-commerce: Online stores (WooCommerce, Shopify, etc.)
  • Blog: Blogging platforms (Ghost, Jekyll, etc.)
  • API: Backend APIs (Node.js, Python, Go, etc.)
  • Frontend: Single Page Applications (React, Vue, Angular, etc.)
  • Database: Database applications (phpMyAdmin, pgAdmin, etc.)
  • Monitoring: Monitoring tools (Grafana, Prometheus, etc.)
  • Development: Development tools (GitLab, Jenkins, etc.)

Supported Dependencies

ServiceTypeVersionsAuto-Injected Variables
PostgreSQLdatabase13, 14, 15, 16Connection strings and credentials
MySQLdatabase5.7, 8.0Connection strings and credentials
Rediscache6, 7Connection URLs and endpoints
RabbitMQqueue3.11, 3.12Connection URLs and credentials
MongoDBdatabase5.0, 6.0, 7.0Connection strings and credentials

Dependency Configuration Examples

dependencies:
  # PostgreSQL database
  - name: "postgres"  
    type: "POSTGRESQL"
    version: "15"
    storage_size: "5Gi"

  # Redis cache
  - name: "cache"
    type: "REDIS" 
    version: "7"
    storage_size: "1Gi"

  # RabbitMQ message queue
  - name: "queue"
    type: "RABBITMQ"
    version: "3.12"
    storage_size: "2Gi"

Configuration Reference

Detailed explanation of each configuration item in deployaja.yaml

Application Metadata

FieldTypeRequiredDescriptionExample
namestring✅ YesUnique application name. Must be lowercase, alphanumeric with hyphens."arjuna-23-app"
descriptionstring❌ NoHuman-readable description of your application."My awesome web API"

Container Configuration

FieldTypeRequiredDescriptionExample
container.imagestring✅ YesDocker image reference."node:18-alpine"
"ghcr.io/user/app:v1.0"
container.portinteger✅ YesPort your application listens on inside the container.3000, 8080, 80
container.commandarray❌ NoOverride container's default command.["npm", "start"]
container.argsarray❌ NoArguments passed to the container command.["--port", "3000"]

Resource Requirements

FieldTypeRequiredDescriptionExample
resources.cpustring❌ NoCPU request in millicores (m) or cores."100m", "1", "2.5"
resources.memorystring❌ NoMemory request in bytes (Ki, Mi, Gi)."128Mi", "1Gi", "2.5Gi"
resources.replicasinteger❌ NoNumber of application instances to run.1, 2, 3

Environment Variables

FieldTypeRequiredDescriptionExample
env[].namestring✅ YesEnvironment variable name."NODE_ENV", "API_KEY"
env[].valuestring✅ YesEnvironment variable value."production", "info"
env[].secretboolean❌ NoMark as secret. Value will be encrypted.true

Environment Mapping

FieldTypeRequiredDescriptionExample
envMapobject❌ NoMaps values from source keys to destination environment variables.db_host: WORDPRESS_DB_HOST

Configuration Example

# Application metadata
name: "arjuna-23-app"
description: "My awesome app"

# Container configuration
container:
  image: "node:18-alpine"
  port: 3000

# Resource requirements
resources:
  cpu: "500m"
  memory: "1Gi"
  replicas: 2

# Dependencies
dependencies:
  - name: "postgres"
    type: "POSTGRESQL"
    version: "15"
    storage_size: "2Gi"

# Environment variables
env:
  - name: "NODE_ENV"
    value: "production"
  - name: "LOG_LEVEL"
    value: "info"

# Environment mapping
envMap:
  postgres_host: DATABASE_HOST
  postgres_url: DATABASE_URL

Environment Mapping

Environment mapping allows you to map values from one environment variable to another, providing flexible configuration management for your applications.

What is envMap?

The envMap feature allows you to create mappings between environment variables. This is particularly useful when you need to:

  • Map dependency connection details to application-specific environment variables
  • Transform variable names to match your application's expected format
  • Create aliases for environment variables with different naming conventions
  • Integrate with third-party applications that expect specific variable names

🔧 How it Works

When you define an envMap, the system takes the value from the source key and sets it as the value for the destination environment variable.

# Basic syntax
envMap:
  source_key: DESTINATION_ENV_VAR

In this example, the value stored in source_key will be assigned to the DESTINATION_ENV_VAR environment variable in your application container.

Configuration Examples

Basic WordPress Example

name: "wordpress-site"
container:
  image: "wordpress:latest"
  port: 80

dependencies:
  - name: "db"
    type: "MYSQL"
    version: "8.0"

# Environment variable mapping
envMap:
  db_host: WORDPRESS_DB_HOST
  db_name: WORDPRESS_DB_NAME
  db_user: WORDPRESS_DB_USER
  db_password: WORDPRESS_DB_PASSWORD

Advanced Node.js API Example

name: "nodejs-api"
container:
  image: "node:18-alpine"
  port: 3000

dependencies:
  - name: "postgres"
    type: "POSTGRESQL"
    version: "15"
  - name: "redis"
    type: "REDIS"
    version: "7"

env:
  - name: "NODE_ENV"
    value: "production"
  - name: "PORT"
    value: "3000"

# Map dependency variables to application-specific names
envMap:
  postgres_host: DATABASE_HOST
  postgres_port: DATABASE_PORT
  postgres_db: DATABASE_NAME
  postgres_user: DATABASE_USER
  postgres_password: DATABASE_PASSWORD
  redis_host: CACHE_HOST
  redis_port: CACHE_PORT
  redis_url: CACHE_URL

Common Source Keys

When you create dependencies, the system automatically generates several environment variables that you can use as source keys in your envMap:

Dependency TypeAvailable Source KeysDescription
PostgreSQLdb_host
db_port
db_name
db_user
db_password
jdbc_url jdbc_url_no_auth
Database connection details and connection string
MySQLdb_host
db_port
db_name
db_user
db_password
jdbc_url jdbc_url_no_auth
Database connection details and connection string
Redisredis_host
redis_port
redis_url
Cache server connection details
RabbitMQrabbitmq_host
rabbitmq_port
rabbitmq_user
rabbitmq_password
rabbitmq_url
Message queue connection details
MongoDBmongodb_host
mongodb_port
mongodb_db
mongodb_user
mongodb_password
mongodb_url
NoSQL database connection details

Best Practices

  • Use descriptive names: Choose destination variable names that clearly indicate their purpose
  • Follow conventions: Use your application's existing naming conventions for environment variables
  • Document mappings: Keep track of which source keys map to which destination variables
  • Test thoroughly: Always test your application with the mapped environment variables
  • Use connection strings: For databases, consider using full connection URLs when possible

Common Use Cases

1. Legacy Application Integration

When integrating with applications that expect specific environment variable names:

envMap:
  postgres_host: DB_HOST        # Legacy app expects DB_HOST
  postgres_user: DB_USERNAME   # Legacy app expects DB_USERNAME

2. Framework-Specific Requirements

Different frameworks may have specific naming requirements:

# Django application
envMap:
  postgres_host: DB_HOST
  postgres_db: DB_NAME
  postgres_user: DB_USER
  postgres_password: DB_PASSWORD

# Rails application
envMap:
  postgres_url: DATABASE_URL

3. Multiple Services

When your application connects to multiple instances of the same service:

dependencies:
  - name: "primary-db"
    type: "POSTGRESQL"
  - name: "analytics-db"
    type: "POSTGRESQL"

envMap:
  primary_db_url: PRIMARY_DATABASE_URL
  analytics_db_url: ANALYTICS_DATABASE_URL

Troubleshooting

Common Issues

Authentication Errors

# Clear stored token and re-authenticate
rm ~/.deployaja/token
aja login

Deployment Failures

# Check deployment status
aja status

# Get detailed pod information and events
aja describe my-app

# View logs for errors
aja logs my-app --tail=100

# Follow logs in real-time for debugging
aja logs my-app -f

# Validate configuration
aja validate

FAQ

How do I check if my deployment is healthy?

Use aja status to see the overall health of your deployments, or aja describe [name] for detailed information about a specific deployment.

My application isn't starting. What should I check?

Check the logs with aja logs [name] and verify your configuration with aja validate. Common issues include wrong port numbers, missing environment variables, or image pull failures.

How do I scale my application?

Update the resources.replicas field in your configuration and redeploy with aja deploy.

Development

Contributing

We welcome contributions! Here's how to get started:

# Clone repository
git clone https://github.com/deployaja/deployaja-cli.git
cd deployaja-cli

# Install dependencies
go mod tidy

# Run tests
go test ./...

# Build
go build -o aja main.go

# Run
./aja --help

Tech Stack

  • Cobra - CLI framework
  • Viper - Configuration management
  • Color - Colored terminal output
  • Browser - Browser launching for OAuth
  • UUID - UUID generation