TrueNAS Installation

Overview

This guide walks you through installing ANDO CI Server on TrueNAS SCALE using Docker Compose. ANDO connects to an existing SQL Server instance running on your TrueNAS.

Prerequisites

Before starting, ensure you have:

• TrueNAS SCALE 24.10 or later (earlier versions used Kubernetes)
• Apps pool configured — a storage pool designated for application data
• SQL Server — already running as a container on TrueNAS (install from the app catalog if needed)
• GitHub App credentials — App ID, Client ID, Client Secret, Webhook Secret, and private key file
• A domain name pointing to your TrueNAS server (for HTTPS and GitHub webhooks)

Gather Required Information

You will need these values during installation:

Setting	Description
GitHub__AppId	Your GitHub App’s numeric ID
GitHub__ClientId	OAuth Client ID from GitHub App settings
GitHub__ClientSecret	OAuth Client Secret from GitHub App settings
GitHub__WebhookSecret	Secret for validating webhook payloads
Encryption__Key	Base64-encoded 32-byte key (generate with openssl rand -base64 32)
Server__BaseUrl	Your server’s public URL (e.g., https://ci.example.com)
Email provider	API key or SMTP credentials (see Step 1)

Create Dataset and Directories

Before starting the installation, create a dataset for persistent storage.

1. Navigate to Datasets in TrueNAS
2. Create a dataset: apps/ando (or similar, under your apps pool)
3. Create subdirectories inside the dataset using the TrueNAS Shell or SSH:

mkdir -p /mnt/YOUR_POOL/apps/ando/{artifacts,repos,keys,config}

4. Upload your GitHub App private key to /mnt/YOUR_POOL/apps/ando/config/github-app.pem

Step 1: Create Database and User

Connect to your existing SQL Server and create a dedicated database and login for ANDO.

You can use any SQL client (Azure Data Studio, SSMS, etc.) or sqlcmd. Connect to your TrueNAS IP on the SQL Server port (typically 1433) as sa.

From a machine with sqlcmd installed:

sqlcmd -S YOUR_TRUENAS_IP,1433 -U sa -P 'YOUR_SA_PASSWORD' -C

Run these SQL commands to create the database and user:

-- Create database
CREATE DATABASE AndoServer;
GO

-- Create login
CREATE LOGIN ando WITH PASSWORD = 'YourAndoPassword123!';
GO

-- Create user and grant permissions
USE AndoServer;
GO

CREATE USER ando FOR LOGIN ando;
GO

ALTER ROLE db_owner ADD MEMBER ando;
GO

Type exit to quit sqlcmd.

Important: Replace YourAndoPassword123! with a strong password. You’ll use this in the connection string below.

Step 2: Note Your SQL Server Connection

ANDO connects to SQL Server via TCP on the mapped port. Use your TrueNAS host IP (e.g., 192.168.1.100) with the port your SQL Server is mapped to (typically 1433).

Step 3: Open the YAML Installation Wizard

1. Navigate to Apps → Discover Apps
2. Click the three-dot menu (⋮) in the top right
3. Select Install via YAML

Step 4: Configure the Application

Application Name

Enter: ando

Docker Compose Configuration

Paste the following YAML, replacing the placeholder values:

services:
  ando-server:
    image: ghcr.io/aduggleby/ando-server:latest
    pull_policy: always
    ports:
      - "8080:8080"
    environment:
      - ASPNETCORE_ENVIRONMENT=Production
      # TrueNAS runs Docker as root - acknowledge this security consideration
      - Build__AcknowledgeRootDockerRisk=true
      # Update connection string with your SQL Server details
      - ConnectionStrings__DefaultConnection=Server=YOUR_TRUENAS_IP,1433;Database=AndoServer;User Id=ando;Password=YOUR_ANDO_PASSWORD;TrustServerCertificate=true
      # Replace with your GitHub App credentials
      - GitHub__AppId=YOUR_APP_ID
      - GitHub__ClientId=YOUR_CLIENT_ID
      - GitHub__ClientSecret=YOUR_CLIENT_SECRET
      - GitHub__WebhookSecret=YOUR_WEBHOOK_SECRET
      # Generate with: openssl rand -base64 32
      - Encryption__Key=YOUR_ENCRYPTION_KEY
      # Public URL for email links (verification, password reset)
      - Server__BaseUrl=https://your-domain.com
      # Email configuration (choose one provider)
      # Option A: Resend-compatible API (recommended) - e.g., SelfMX
      - [email protected]
      - Email__Provider=Resend
      - Email__Resend__ApiKey=YOUR_API_KEY
      - Email__Resend__BaseUrl=https://api.selfmx.com/
      # For official Resend, omit BaseUrl or use: https://api.resend.com/
      # Option B: SMTP
      # - Email__Provider=Smtp
      # - Email__Smtp__Host=smtp.yourdomain.com
      # - Email__Smtp__Port=587
      # - Email__Smtp__Username=YOUR_SMTP_USER
      # - Email__Smtp__Password=YOUR_SMTP_PASSWORD
    volumes:
      # Docker socket for running builds
      - /var/run/docker.sock:/var/run/docker.sock
      # Persistent storage - update paths to match your pool
      - /mnt/YOUR_POOL/apps/ando/artifacts:/data/artifacts
      - /mnt/YOUR_POOL/apps/ando/repos:/data/repos
      - /mnt/YOUR_POOL/apps/ando/keys:/data/keys
      - /mnt/YOUR_POOL/apps/ando/config/github-app.pem:/app/github-app.pem:ro
    restart: unless-stopped
    privileged: true

Values to Replace

Placeholder	Replace With
YOUR_TRUENAS_IP	Your TrueNAS host IP address (e.g., 192.168.1.100)
1433	The port your SQL Server is mapped to (change if different)
YOUR_ANDO_PASSWORD	The password you set for the ando login in Step 1
YOUR_POOL	Your TrueNAS pool name (e.g., tank, data)
YOUR_APP_ID	GitHub App numeric ID
YOUR_CLIENT_ID	GitHub OAuth Client ID
YOUR_CLIENT_SECRET	GitHub OAuth Client Secret
YOUR_WEBHOOK_SECRET	GitHub webhook secret
YOUR_ENCRYPTION_KEY	Base64 key from openssl rand -base64 32
https://your-domain.com	Your server’s public URL (for email links)
YOUR_API_KEY	API key for your Resend-compatible email provider (e.g., SelfMX)
https://api.selfmx.com/	Base URL for your email provider’s API
[email protected]	Your verified sender email address

Step 5: Install

Click Install to deploy the container. TrueNAS will pull the Docker image and start ANDO.

Step 6: Configure Reverse Proxy

For HTTPS access and GitHub webhooks, configure a reverse proxy.

Option A: TrueNAS Built-in or Traefik

If your TrueNAS has a public IP:

1. Install Traefik from the TrueNAS app catalog
2. Configure it to proxy your-domain.com → localhost:8080

Option B: External Reverse Proxy

If using Caddy, nginx, or another external proxy:

# Example Caddy configuration
your-domain.com {
    reverse_proxy YOUR_TRUENAS_IP:8080
}

Step 7: Configure GitHub App

Update your GitHub App 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

Verification

1. Access the ANDO dashboard at http://YOUR_TRUENAS_IP:8080 (or your HTTPS domain)
2. Click Sign in with GitHub to test OAuth
3. Connect a repository and trigger a test build

Updating ANDO

To update to a new version:

1. Navigate to Apps → Installed Applications
2. Click on ando
3. Click Edit → update the image tag or use latest → Save

The container will restart with the new version.

Troubleshooting

View Logs

1. Navigate to Apps → Installed Applications
2. Click on ando
3. Click Logs to view the container output

Container Won’t Start

Check that:

• All dataset paths exist and are accessible
• The github-app.pem file is uploaded to the config directory
• Environment variables are correctly formatted (no extra spaces)

Database Connection Failed

1. Verify the TrueNAS IP and port are correct
2. Test the connection: nc -zv YOUR_TRUENAS_IP 1433
3. Verify the ando login was created correctly
4. Check the password matches what you set in Step 1

Builds Fail with Docker Errors

Verify:

• The Docker socket path /var/run/docker.sock exists on your TrueNAS system
• The privileged: true setting is in place

Permission Denied on Mounted Volumes

TrueNAS may need ACL configuration:

1. Navigate to the dataset in Datasets
2. Click Edit Permissions
3. Add an ACL entry for UID 0 (root) with full access

More Information

• Main CI Server Documentation
• GitHub App Configuration
• TrueNAS Custom Apps Documentation