Alphie – Installer

1. What this installer does

When you run ./alphie.installer as root on a supported server, it automates the setup of Alphie and its dependencies.

The installer will:

• Verify that the OS is supported and exit if it is not.
• Run dnf / apt-get update and apt-get upgrade.
• Install required packages, including:
  • git, python3, python3-pip
  • nginx
  • wget, tar, unzip
  • podman, screen, uidmap, slirp4netns, fuse-overlayfs
  • Build and Python dev libs: build-essential, python3-dev, libpq-dev, libffi-dev, libssl-dev
• Install certbot (and Nginx plugin) via DNF or APT, if needed.
• Install required Python modules system-wide (FastAPI, Uvicorn, SQLAlchemy, psycopg2, cryptography, etc.) and verify they import correctly.
• Set up PostgreSQL:
  • Either connect to an external PostgreSQL server, or
  • Install and configure a local PostgreSQL server, user, and database.
• Create /etc/alphie/alphie.env containing:
  • DATABASE_URL
  • FERNET_KEY (encryption key for secrets)
• Set up TLS/SSL for Nginx using either existing certs or a self-signed certificate.
• Configure an Alphie Nginx site from the included template.
• Optionally populate the database schema and default data.
• Deploy the ./alphie directory to /opt/alphie (with backups of any existing install).
• Install and start the alphie.service systemd unit.
• Prompt you to create/update an admin user and generate an API client ID/secret.
• Print a final summary with URLs to access the web UI.

2. Prerequisites

• A Supported server using dnf / apt.
• Root access (run as root or via sudo).
• Outbound internet access for DNF, APT and Python packages.
• A DNS name for the server is recommended for HTTPS and Nginx configuration.

3. Package layout

After extracting the Alphie distribution, you should see something like:

• alphie.installer — the installer script
• alphie/ — the Alphie application directory
• etc/nginx/alphie.conf — Nginx site template
• etc/system/alphie.service — systemd unit file
• scripts/db_scripts/... — database schema and seed SQL files

Important: Run the installer from the directory where you unpacked the package so it can find alphie/, etc/, and scripts/.

4. How to run the installer

1. Copy the Alphie install package to your server and extract it, for example:

   tar xzf alphie_installer.tgz
   cd alphie_installer

2. Make the installer executable:

   chmod +x alphie.installer

3. Run it as root:

   sudo ./alphie.installer

4. Follow the prompts. The script is interactive and will ask about PostgreSQL, TLS, Nginx, and admin user setup.

5. Installer questions (what to expect)

5.1 OS confirmation

Prompt:

Q1) Is this an [ Supported OS ] server? [y/n] (detected: ...)

• Answer y for [ Supported OS ].
• If you answer n, the installer exits.

5.2 PostgreSQL: external vs local

Prompt:

Q) Is your PostgreSQL server external or local? [external/local] (default: local)

You can point Alphie to an external PostgreSQL server or have the installer set up a local one.

Option A: External PostgreSQL

If you choose external, you will be asked for:

• Host (e.g. db.example.com)
• Port (default 5432)
• Database name (default alphie)
• Username (default ansible_admin)
• Password (masked input)

The installer builds a DATABASE_URL like postgresql://user:pass@host:port/dbname and tests the connection. For external DBs, Alphie assumes the database and user already exist with proper permissions.

Option B: Local PostgreSQL (recommended for simple installs)

If you choose local (or accept the default), the installer will:

• Install postgresql and postgresql-contrib.
• Start and enable the PostgreSQL service.
• Ask for DB name (default alphie), DB user (default ansible_admin), and a password.
• Create or update the role and database if they do not exist.
• Grant permissions on the public schema.
• Update pg_hba.conf to use password auth (md5), then reload PostgreSQL.

5.3 TLS / SSL certificate

Prompt:

Do you already have TLS certs for this server? [y/N]:

If you answer “yes”

You’ll provide paths to:

• Your existing certificate file (.crt/.pem)
• Your existing private key file (.key/.pem)

The installer copies them into the appropriate locations for Nginx.

If you answer “no” or press Enter

The installer will:

• Ask for a Common Name (CN) – usually your Alphie DNS name.
• Use openssl to generate a self-signed cert:
  • /etc/ssl/private/alphie.key
  • /etc/ssl/certs/alphie.crt

Note: The openssl prompt can be answered minimally if the cert is for internal use.

5.4 Nginx server name

Prompt:

Nginx server_name to use [your.server.name]:

Enter the DNS name users will type to reach Alphie (for example alphie.example.com). The installer updates the Nginx config, copies it into /etc/nginx/conf.d/, tests the config, and reloads or restarts Nginx.

5.5 Database schema population

Prompt:

Q) Populate the database with schema files now? [y/n] (default: n)

If you answer y (recommended for fresh installs), the installer:

• Applies the schema from scripts/db_scripts/db_schema_out/.
• Runs default_add.sql to insert default data.

If you answer n, the database is left empty for you to manage manually.

5.6 Admin user creation

At the end, you’ll be prompted to set up your initial admin user:

• Admin username (default admin)
• Password (entered twice, masked)

The installer will:

• Hash the password with bcrypt and encrypt it with your FERNET_KEY.
• Insert or update the admin user in the users table.
• Create or update an API client ID and secret for this user and show the plain client secret once.

6. After the installer finishes

When the script completes, you’ll see a summary including:

• The status of alphie.service (should be active).
• Your URLs:
  • Via DNS, e.g. https://alphie.example.com
  • Via IP, e.g. https://10.x.x.x
• Your admin username.
• The location of the env file: /etc/alphie/alphie.env.

Next steps:

1. Open a browser and go to the HTTPS URL (DNS or IP).
2. Log in with the admin username and password you configured.
3. Store your API client ID/secret somewhere safe if you plan to use the API.

7. Notes & troubleshooting

• Run as root: The installer requires root privileges and will exit if not run as root.
• Firewall: If ufw is present, the script opens HTTPS and port 8000. Otherwise, ensure port 443 (and any other relevant ports) are reachable.
• Check the service:

  systemctl status alphie.service

• View logs:

  journalctl -u alphie.service -n 100 --no-pager

• Re-running the installer: If /opt/alphie exists, it is backed up as /opt/alphie.bak.<timestamp> and a fresh copy is deployed. The env file is also backed up before being overwritten.