Installation & Operations

Prerequisites

Resource checks during installation are warnings only — they will not block installation.

Supported Operating Systems

Ubuntu 22.04/24.04, Debian 12, AlmaLinux 9, Rocky Linux 9, RHEL 9.

Network Requirements

• Outbound HTTPS (443) for Docker Hub image pulls and LLM API calls
• Inbound HTTPS (443) for user access
• Port 8471 outbound to IBM i (for AS/400 extraction)

Quick Install

curl -fsSL https://afunana.io/setup.sh -o setup.sh && bash setup.sh

This single command downloads the installer and runs it interactively. It detects your OS, installs Docker if missing, pulls Afunana images, generates all secrets (JWT, database passwords, deploy token), creates the directory structure at /opt/afunana, starts all services, runs schema migrations, creates the initial admin user, and prints the access URL.

During installation you will be prompted for a Docker Hub access token (provided by the Afunana team), admin credentials, organization name, and an optional domain name for HTTPS.

Directory Structure

/opt/afunana/
|-- docker-compose.yml
|-- secrets/                  # Auto-generated Docker secrets
|-- backend/
|   |-- .env                  # Bootstrap configuration
|   +-- Data/                 # Collection data (source, analysis, indices)
|-- client/dist/              # Built frontend (served by Caddy)
|-- db/                       # Schema and seed SQL
|-- backups/                  # Daily database backups
+-- logs/                     # Application logs

Database Options

Built-in SQL Server (Default)

The installer deploys a containerized SQL Server 2022 instance with automatic daily backups and TDE encryption (AES-256). No external database required.

External SQL Server

For centrally managed databases, provide connection details during install:

DB_SERVER=your-sql-server.internal
DB_PORT=1433
DB_DATABASE=afunana
DB_USER=afunana_app
DB_PASSWORD=<strong-password>

Requirements: SQL Server 2019+, an empty database, and a login with db_datareader, db_datawriter, and CREATE TABLE permissions.

Post-Install Configuration

Configuration is split into two layers: bootstrap values (required at startup) and runtime values (editable live via Admin panel).

Bootstrap Configuration (.env / Docker Secrets)

Docker secrets (/run/secrets/): db_password, jwt_secret, deploy_secret, openai_api_key, anthropic_api_key, as400_password.

Runtime Configuration (Database)

Stored in the app_config table, managed through Admin → Configuration. Changes take effect immediately without restart.

HTTPS & Domain Setup

Afunana uses Caddy as its web server, which automatically provisions TLS certificates from Let's Encrypt when a domain name is configured.

During Installation

The installer asks for a domain name. If you provide one (e.g. app.yourcompany.com), Caddy will automatically:

• Obtain a TLS certificate from Let's Encrypt
• Serve the application over HTTPS
• Redirect HTTP to HTTPS

Prerequisites: The domain's DNS A record must point to the server's IP address, and ports 80 and 443 must be open (Let's Encrypt uses port 80 for certificate challenges).

Adding a Domain After Installation

If you installed without a domain (IP-only mode), you can add one later by re-running the installer and choosing option 3:

curl -fsSL https://afunana.io/setup.sh -o setup.sh && bash setup.sh
# Choose option 3: Reconfigure domain
# Enter your domain name

Caddy will restart and provision the certificate within seconds. No other changes are needed.

IP-only Mode (No Domain)

If no domain is provided, the application runs on HTTP only, accessible via the server's IP address. This is suitable for internal/VPN environments where HTTPS is terminated at a load balancer or reverse proxy upstream.

Updates & Deployment

Afunana uses Docker Hub image distribution. Updates are pulled on the customer's schedule.

Manual Update

cd /opt/afunana
docker compose pull
docker compose up -d

Database schema migrations run automatically on startup. Schema changes are forward-only and idempotent.

Update Check

The admin panel checks https://afunana.io/latest-version.json and displays a notification when a new version is available. API: GET /admin/actions/check-update.

Deploy Receiver (Optional)

For automated updates, install the deploy receiver service. It listens on port 9000 for webhook calls, pulls latest code, rebuilds containers, and applies schema changes.

# Install
cp deploy_receiver.service /etc/systemd/system/
systemctl enable --now deploy_receiver

# Trigger
POST /deploy-hook with X-Deploy-Token header

Rollback

docker image ls dovk/afunana-app          # List available versions
docker compose pull dovk/afunana-app:<tag>  # Pull specific version
docker compose up -d

Backup & Recovery

Automated Backups

Daily at 02:00 UTC via cron. Location: /opt/afunana/backups/. Format: afunana_YYYYMMDD_HHMMSS.bak. Retention: 7 days (configurable via BACKUP_RETAIN_DAYS). SQL Server native compression with checksum.

Manual Backup

/opt/afunana/scripts/backup-db.sh

Restore

docker exec sqlserver /opt/mssql-tools18/bin/sqlcmd \
  -S localhost -U sa -P "$SA_PASSWORD" \
  -Q "RESTORE DATABASE afunana FROM DISK='/var/opt/mssql/backup/afunana_YYYYMMDD.bak' WITH REPLACE"

Monitoring

Health Endpoint

GET /health    # No auth required
{
  "status": "ok",
  "version": "0.2.82",
  "checks": { "database": "ok", "as400": "ok" },
  "timestamp": "2026-05-23T17:21:10Z"
}

Docker monitors this endpoint every 30 seconds. If 3 consecutive checks fail, the container restarts automatically.

Logs

docker compose logs -f afunana-app    # Application
docker compose logs -f caddy          # Web server
docker compose logs -f sqlserver      # Database
journalctl -u deploy_receiver -f      # Deploy receiver

Troubleshooting