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 | iexBuild from Source
git clone https://github.com/deployaja/deployaja-cli.git
cd deployaja-cli
go build -o aja main.goUsing Docker
docker pull ghcr.io/deployaja/deployaja-cli/ajaDeploy 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/adminGitHub 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
| Input | Description | Required | Default |
|---|---|---|---|
command | DeployAja command to execute | Yes | status |
api-token | DeployAja API token for authentication | No | - |
config-file | Path to DeployAja configuration file | No | ./deployaja.yaml |
environment | Target environment for deployment | No | production |
project-name | Name of the project to deploy | No | - |
additional-args | Additional arguments to pass to the CLI | No | - |
Action Outputs
| Output | Description |
|---|---|
deployment-id | ID of the created deployment |
deployment-url | URL of the deployed application |
status | Status 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
| Command | Description |
|---|---|
aja init | Create deployaja.yaml configuration with random Wayang-inspired name |
aja gen PROMPT | Generate deployment configuration using AI based on natural language prompt |
aja validate | Validate configuration file |
aja plan | Show deployment plan and costs |
aja deploy | Deploy application |
aja status | Check deployment health and status |
aja describe NAME | Describe deployment pod details (status, containers, events, etc.) |
aja logs NAME | View application logs |
Management Commands
| Command | Description |
|---|---|
aja env [edit|set|get] | Manage environment variables |
aja restart NAME | Restart deployment by recreating pods |
aja drop NAME | Delete deployment |
aja rollback NAME | Rollback to previous version |
Utility Commands
| Command | Description |
|---|---|
aja deps [instance] | List available dependencies and versions |
aja login | Authenticate with platform using browser OAuth |
aja config | Show configuration |
aja search QUERY | Search for apps in the marketplace |
aja list | List all marketplace apps with filtering and pagination |
aja install APPNAME | Install an app from the marketplace |
aja publish | Publish your app to the marketplace |
aja upgrade | Upgrade CLI to the latest version |
aja version | Show 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 upgradeMarketplace
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 appAvailable 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
| Service | Type | Versions | Auto-Injected Variables |
|---|---|---|---|
| PostgreSQL | database | 13, 14, 15, 16 | Connection strings and credentials |
| MySQL | database | 5.7, 8.0 | Connection strings and credentials |
| Redis | cache | 6, 7 | Connection URLs and endpoints |
| RabbitMQ | queue | 3.11, 3.12 | Connection URLs and credentials |
| MongoDB | database | 5.0, 6.0, 7.0 | Connection 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
| Field | Type | Required | Description | Example |
|---|---|---|---|---|
name | string | ✅ Yes | Unique application name. Must be lowercase, alphanumeric with hyphens. | "arjuna-23-app" |
description | string | ❌ No | Human-readable description of your application. | "My awesome web API" |
Container Configuration
| Field | Type | Required | Description | Example |
|---|---|---|---|---|
container.image | string | ✅ Yes | Docker image reference. | "node:18-alpine""ghcr.io/user/app:v1.0" |
container.port | integer | ✅ Yes | Port your application listens on inside the container. | 3000, 8080, 80 |
container.command | array | ❌ No | Override container's default command. | ["npm", "start"] |
container.args | array | ❌ No | Arguments passed to the container command. | ["--port", "3000"] |
Resource Requirements
| Field | Type | Required | Description | Example |
|---|---|---|---|---|
resources.cpu | string | ❌ No | CPU request in millicores (m) or cores. | "100m", "1", "2.5" |
resources.memory | string | ❌ No | Memory request in bytes (Ki, Mi, Gi). | "128Mi", "1Gi", "2.5Gi" |
resources.replicas | integer | ❌ No | Number of application instances to run. | 1, 2, 3 |
Environment Variables
| Field | Type | Required | Description | Example |
|---|---|---|---|---|
env[].name | string | ✅ Yes | Environment variable name. | "NODE_ENV", "API_KEY" |
env[].value | string | ✅ Yes | Environment variable value. | "production", "info" |
env[].secret | boolean | ❌ No | Mark as secret. Value will be encrypted. | true |
Environment Mapping
| Field | Type | Required | Description | Example |
|---|---|---|---|---|
envMap | object | ❌ No | Maps 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_URLEnvironment 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_VARIn 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_PASSWORDAdvanced 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_URLCommon Source Keys
When you create dependencies, the system automatically generates several environment variables that you can use as source keys in your envMap:
| Dependency Type | Available Source Keys | Description |
|---|---|---|
| PostgreSQL | db_hostdb_portdb_namedb_userdb_passwordjdbc_url jdbc_url_no_auth | Database connection details and connection string |
| MySQL | db_hostdb_portdb_namedb_userdb_passwordjdbc_url jdbc_url_no_auth | Database connection details and connection string |
| Redis | redis_hostredis_portredis_url | Cache server connection details |
| RabbitMQ | rabbitmq_hostrabbitmq_portrabbitmq_userrabbitmq_passwordrabbitmq_url | Message queue connection details |
| MongoDB | mongodb_hostmongodb_portmongodb_dbmongodb_usermongodb_passwordmongodb_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_USERNAME2. 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_URL3. 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_URLTroubleshooting
Common Issues
Authentication Errors
# Clear stored token and re-authenticate
rm ~/.deployaja/token
aja loginDeployment 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 validateFAQ
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 --helpTech Stack
- Cobra - CLI framework
- Viper - Configuration management
- Color - Colored terminal output
- Browser - Browser launching for OAuth
- UUID - UUID generation