Installation Guide

This page covers installing Squad Aegis with Docker Compose and building it from source. The Docker Compose path is the supported way to run it.

Prerequisites

Before installing Squad Aegis, ensure you have:

• Docker Engine 20.10.0 or newer
• Docker Compose V2
• 4 GB RAM minimum
• 10 GB available storage
• Familiarity with Docker and the command line

1. Clone the Repository

git clone https://github.com/Codycody31/squad-aegis.git
cd squad-aegis

2. Configure Environment Variables

Create a .env file in the project root (same directory as docker-compose.yml). Here is a template you can customize:

# Application Configuration
APP_IS_DEVELOPMENT=false
APP_WEB_UI_PROXY=
APP_PORT=3113
APP_URL=http://localhost:3113
APP_IN_CONTAINER=false

# Initial Admin User
INITIAL_ADMIN_USERNAME=admin
INITIAL_ADMIN_PASSWORD=your_secure_password

# Database Configuration
DB_HOST=database
DB_PORT=5432
DB_NAME=squad-aegis
DB_USER=squad-aegis
DB_PASS=squad-aegis
DB_MIGRATE_VERBOSE=false

# ClickHouse Configuration
CLICK_HOUSE_HOST=clickhouse
CLICK_HOUSE_PORT=9000
CLICK_HOUSE_DATABASE=default
CLICK_HOUSE_USERNAME=squad_aegis
CLICK_HOUSE_PASSWORD=squad_aegis
CLICK_HOUSE_DEBUG=false

# Valkey Configuration
VALKEY_HOST=valkey
VALKEY_PORT=6379

# Logging Configuration
LOG_LEVEL=info
LOG_SHOW_GIN=false
LOG_FILE=

# Debug Configuration
DEBUG_PRETTY=true
DEBUG_NO_COLOR=false

Security: change INITIAL_ADMIN_PASSWORD and every database credential before deploying. The values above are placeholders.

3. Running with Docker Compose

Option A: Quick Start (non-dev stack)

Run everything with the production-style docker-compose.yml:

docker compose up -d

This will start the following containers:

• PostgreSQL 14 - main application database
• ClickHouse 25.3 - analytics database
• Valkey 8.1.3 - caching / key-value store
• Squad Aegis Server - main application

Option B: Development stack

If you want to build locally and run alongside databases:

docker compose -f docker-compose.dev.yml up -d

Update .env and the database connection settings before starting this stack.

4. (Optional) Build the Application Yourself

If you prefer to build the server and web UI locally before containerizing:

# Install dependencies
go mod tidy
go mod vendor

# Build the server (includes web UI)
make build-server

# Or build everything
make build

This will create binaries in the dist/ directory.

You can also build your own Docker image:

docker build -f docker/Dockerfile.multiarch.rootless -t squad-aegis:latest .

Then edit docker-compose.yml to use:

image: squad-aegis:latest

5. Database Migration

The application automatically runs database migrations on startup. Check migration status:

docker compose logs -f squad-aegis

6. Verify and Access the Application

Check logs:

docker compose logs -f

Check container health:

docker ps

Open http://localhost:3113 in a browser.

Log in with:

• Username: admin
• Password: the one you set in .env

7. Stopping & Restarting

To stop the stack:

docker compose down

To restart:

docker compose up -d

8. Data Persistence

The following named volumes persist data across container restarts:

9. Post-Installation Steps

1. Change Default Credentials immediately after first login
2. Configure Servers: Add your Squad servers in the web UI
3. Set Up Users with appropriate permissions
4. Configure Plugins as needed

Troubleshooting

Common Issues

1. Port Already in Use

   • Change APP_PORT in .env
   • Update the port mapping in docker-compose.yml

2. Database Connection Errors

   • Verify the database container is running
   • Check connection parameters in .env
   • Ensure user permissions are correct

3. Permission Issues

   • Verify Docker volume permissions

Viewing Logs

# View all service logs
docker compose logs

# View logs for a specific service
docker compose logs squad-aegis

# Follow logs in real-time
docker compose logs -f squad-aegis

Support

• Bug reports and feature requests: Issue Tracker
• Documentation: this site