Getting Started with ACT

This guide will walk you through setting up ACT and deploying your first application.

Prerequisites

• A Linux server with SSH access (Ubuntu 22.04+ recommended)
• Docker installed on your local machine (for building images)
• A domain name pointing to your server (for HTTPS)

Installation

1. Automated Installation (Recommended)

Run the installer to set up ACT, systemd services, and configuration automatically:

curl -fsSL https://raw.githubusercontent.com/drmhse/act2/main/install.sh | bash

2. Manual Installation

If you prefer to install manually:

# 1. Download the latest release
curl -L https://github.com/actplatform/act/releases/latest/download/act-linux-amd64 -o act
chmod +x act
sudo mv act /usr/local/bin/

# 2. Create the configuration and data directories
sudo mkdir -p /etc/act /var/lib/act

# 3. Generate a Setup Token
# This token is required to create the first admin account via the dashboard.
openssl rand -hex 16 | sudo tee /var/lib/act/setup_token
sudo chmod 600 /var/lib/act/setup_token

3. Start the Server

If you used the automated installer:

sudo systemctl start act

If you are running manually:

# Set required environment variables
export DATABASE_URL="sqlite:///var/lib/act/act.db"
export ACT_MASTER_KEY="your-32-byte-encryption-key"
export AUTHOS_URL="https://sso.example.com"
export AUTHOS_AUDIENCE="act"

# Run the server
act

4. Access the Dashboard

Open http://localhost:8080 (default port) in your browser to access the ACT dashboard.

5. Initial Setup (First-to-Claim)

When you first access the dashboard, you will be prompted for a Setup Token. This is a security measure to ensure that only the person who installed ACT can create the initial administrator account.

• Setup Token: Located at /var/lib/act/setup_token on the server.
• Master Key: Located in /etc/act/act.env.

[!CAUTION] Save Your Master Key: The Master Key is used to encrypt all sensitive data (passwords, private keys) in the database. If you lose this key, you will lose access to all managed servers and services. Keep it in a secure password manager.

Add Your First Server

1. Navigate to Servers in the dashboard

2. Click Add Server

3. Enter your server details:

   • Name: A friendly name (e.g., “production-1”)
   • IP Address: Your server’s public IP
   • SSH User: Usually “root” or your admin user
   • SSH Private Key: Your private key for authentication

4. Click Commission to set up Docker and Traefik

   [!IMPORTANT] Firewall Requirement: All servers in your cluster must allow inbound traffic on UDP port 51820 from each other’s public IPs. This is required for the WireGuard Mesh private network.

Deploy Your First Service

1. Navigate to Services in the dashboard
2. Click Create Service
3. Configure your service:
   • Name: Your application name
   • Repository URL: Git repository containing your Dockerfile
   • Branch: The branch to deploy (default: “main”)
   • Domain: Your application’s domain
4. Click Deploy

ACT will:

• Clone your repository
• Auto-detect your project type or use your Dockerfile
• Build the Docker image
• Push to your configured registry
• Deploy with zero-downtime blue/green switching

[!TIP] No Dockerfile? ACT uses Nixpacks to automatically generate optimized Dockerfiles for Node.js, Python, Go, and Rust projects.

Next Steps

• Understanding Deployments - Learn how blue/green deployments work
• Environment Variables - Configure secrets and configuration
• Custom Domains - Set up SSL and routing