ANDO CI Server

Overview

The ANDO CI Server runs your build.csando scripts automatically when you push to GitHub. It provides a web interface for monitoring builds, viewing logs, and managing projects.

Features

• GitHub App Integration: Receives webhooks on push events and reports build status back to GitHub.
• Rootless Docker: Runs under rootless Docker for enhanced security. Build containers are isolated.
• Automatic HTTPS: Caddy reverse proxy automatically obtains and renews Let’s Encrypt certificates.
• Automated Backups: Daily backups with 7-day daily + 12-month monthly retention.

Installation

Linux/Ubuntu Server

Run the installer from your local machine:

curl -fsSL https://andobuild.com/server-install.sh | bash -s user@your-server-ip

Install Options

# Build image locally instead of pulling from ghcr.io
./server-install.sh --build-local user@your-server-ip

# Use an existing SQL Server instead of deploying a container
./server-install.sh --external-sql user@your-server-ip

TrueNAS SCALE

For TrueNAS SCALE installations, see the dedicated guide: TrueNAS Installation

This guide covers installing ANDO as a custom app using the TrueNAS Apps interface.

GitHub App Configuration

Create a GitHub App with these settings:

Setting	Value
Homepage URL	https://your-domain.com
Callback URL	https://your-domain.com/auth/github/callback
Webhook URL	https://your-domain.com/webhooks/github

Required Permissions

Permission	Access
Contents	Read
Metadata	Read
Commit statuses	Read and write

Events

Subscribe to: Push, Pull request

Server Configuration

Configure the server’s public URL in your .env file. This is required for generating links in emails (verification, password reset).

Server__BaseUrl=https://ci.yourdomain.com

The URL must include the scheme (https://) and should not have a trailing slash.

Docker-in-Docker Builds

When a build requires DIND mode (e.g., Docker.Build, Docker.Push), the server automatically installs the Docker CLI inside the build container if it is not already present. This supports Alpine and Debian/Ubuntu-based images. You do not need to call Docker.Install() in your build script when running on the CI server — though it is harmless to include.

Git Identity in Build Containers

The CI server automatically configures a git committer identity (user.name and user.email) inside build containers so that operations like Git.Tag() (annotated tags) work without manual setup.

Defaults: Ando Server / ando-server@localhost

Override via environment variables (checked in order of priority):

1. GIT_COMMITTER_NAME / GIT_COMMITTER_EMAIL (standard git env vars)
2. GIT_AUTHOR_NAME / GIT_AUTHOR_EMAIL
3. GIT_USER_NAME / GIT_USER_EMAIL

Set these in your .env.ando file or CI environment to customize the identity used for tags and commits in your builds. If git config user.name is already set in the container image, the server will not override it.

Docker Security

By default, ANDO CI Server validates that Docker is running in rootless mode for enhanced security. On platforms where Docker runs as root and cannot be configured for rootless mode (such as TrueNAS SCALE), you can bypass this check:

Build__AcknowledgeRootDockerRisk=true

Warning: Running Docker as root allows container escapes to gain root access to the host system. Only use this option on platforms that require it.

Email Configuration

ANDO requires an email service for user registration, password reset, and build failure notifications. Configure one of the following providers in your .env file:

Option A: Resend-Compatible API (Recommended)

Email__Provider=Resend
Email__FromAddress=[email protected]
Email__Resend__ApiKey=your_api_key
Email__Resend__BaseUrl=https://api.selfmx.com/

Works with any Resend-compatible email API such as SelfMX. For the official Resend service, omit BaseUrl or set it to https://api.resend.com/.

Option B: SMTP

Email__Provider=Smtp
Email__FromAddress=[email protected]
Email__Smtp__Host=smtp.yourdomain.com
Email__Smtp__Port=587
Email__Smtp__Username=your-username
Email__Smtp__Password=your-password
Email__Smtp__UseSsl=true

Works with any SMTP provider (Gmail, SendGrid, Mailgun, your own mail server, etc.)

API Tokens

Personal API tokens allow programmatic access to the ANDO CI Server REST API. Use tokens for CI scripts, automation, or any tool that needs to authenticate without a browser session.

Creating a Token

Create tokens via the REST API (requires cookie-based authentication first):

# Login to get a session cookie
curl -c cookies.txt -X POST https://ci.yourdomain.com/api/auth/login \
  -H 'Content-Type: application/json' \
  -d '{"email":"[email protected]","password":"..."}'

# Create a token
curl -b cookies.txt -X POST https://ci.yourdomain.com/api/auth/tokens \
  -H 'Content-Type: application/json' \
  -d '{"name":"CI automation"}'

The response includes the token value once — store it securely. Tokens have the format ando_pat_<random>.

Authenticating with a Token

Pass the token via the Authorization header or the X-Api-Token header:

# Using Authorization header
curl -H 'Authorization: Bearer ando_pat_...' https://ci.yourdomain.com/api/projects

# Using X-Api-Token header
curl -H 'X-Api-Token: ando_pat_...' https://ci.yourdomain.com/api/projects

Token Endpoints

Method	Endpoint	Description
POST	/api/auth/tokens	Create a new token. Body: {"name":"..."}
GET	/api/auth/tokens	List all your tokens (metadata only, not the raw value).
DELETE	/api/auth/tokens/{id}	Revoke a token.

Helper Script

A helper script is included for creating tokens via Playwright’s API context:

ANDO_BASE_URL=https://ci.yourdomain.com \
[email protected] \
ANDO_PASSWORD=... \
ANDO_TOKEN_NAME="CI automation" \
node tests/Ando.Server.E2E/tools/create-api-token.js

Server Management

Management scripts installed to /opt/ando/scripts/:

sudo -u ando /opt/ando/scripts/status.sh   # View container status
sudo -u ando /opt/ando/scripts/logs.sh     # View logs
sudo -u ando /opt/ando/scripts/restart.sh  # Restart services
sudo -u ando /opt/ando/scripts/update.sh   # Pull latest and restart
sudo -u ando /opt/ando/scripts/backup.sh   # Run backup now

File Locations

Path	Description
/opt/ando/docker-compose.yml	Docker Compose configuration
/opt/ando/config/.env	Environment configuration
/opt/ando/scripts/	Management scripts
/opt/ando/backups/	Automated backups
/opt/ando/data/sqldata/	SQL Server database
/opt/ando/data/keys/	ASP.NET Data Protection keys (auth sessions)
/opt/ando/data/artifacts/	Build artifacts

Full Documentation

https://github.com/aduggleby/ando/blob/main/src/Ando.Server/README.md