Installer Architecture

The create-lamaste package is a zero-prompt CLI that provisions a fresh Ubuntu 24.04 droplet with everything needed to run the Lamaste admin panel — in a single command.

In Plain English

When you run npx @lamalibre/create-lamaste on a fresh VPS, the installer takes over and does everything automatically: hardens the OS, installs dependencies, generates security certificates, configures nginx, deploys the panel, and starts the service. It prints a summary with instructions for downloading your client certificate and accessing the panel. No prompts, no questions, no configuration files to edit.

The installer is deliberately limited in scope. It sets up just enough to serve the panel UI over a secure connection. Everything else — domain configuration, tunnel setup, user management — happens through the browser-based onboarding wizard after the installer finishes.

Overview

npx @lamalibre/create-lamaste
  │
  ├── bin/create-lamaste.js          ← CLI entry point
  │     └── calls main() from src/index.js
  │
  └── src/index.js                     ← Listr2 orchestrator
        │
        ├── Phase 1: Environment Checks
        │     ├── checkRoot()          ← Verify running as root
        │     ├── detectOS()           ← Verify Ubuntu 24.04
        │     └── detectIP()           ← Find public IP (DO metadata or hostname)
        │
        ├── detectExistingState()      ← Pre-flight detection
        │     ├── Existing Lamaste?   ← Check /etc/lamalibre/lamaste/panel.json
        │     ├── Existing nginx?      ← List non-lamaste sites-enabled
        │     ├── Port 3100 in use?    ← Check with ss
        │     └── UFW active?          ← Count existing rules
        │
        ├── confirmInstallation()      ← Show banner + warnings, wait for Enter
        │
        ├── Phase 2: Installation Tasks
        │     ├── hardenTasks()        ← Swap, UFW, fail2ban, SSH hardening
        │     ├── nodeTasks()          ← Node.js 20 LTS installation
        │     ├── mtlsTasks()          ← CA + client cert + PKCS12 generation
        │     ├── nginxTasks()         ← Self-signed TLS, mTLS snippet, vhost, nginx start
        │     ├── panelTasks()         ← User, dirs, chisel + Authelia, deploy, config, systemd, sudoers, start
        │     └── gatekeeperTasks()    ← Deploy gatekeeper, state files, systemd, start
        │
        └── printSummary()             ← Formatted box with SCP command + password + URL

Task Execution Order

The installer runs tasks in a strict sequential order. Each task group depends on the outputs of the previous one.

Phase 1: Environment Checks

Three checks run as subtasks of a single Listr2 group:

1. Verify root access — process.getuid() !== 0 → error
2. Detect operating system — parse /etc/os-release, require Ubuntu 24.04
3. Detect IP address — try DigitalOcean metadata API (169.254.169.254), fall back to hostname -I. The --dev flag accepts private IPs for local testing.

Pre-flight Detection

Between Phase 1 and Phase 2, the installer runs detectExistingState() to gather warnings for the confirmation banner. All checks are wrapped in try/catch — detection failures never block the installer.

Detected conditions:

• Existing /etc/lamalibre/lamaste/panel.json → "Re-running will update the installation but preserve your configuration"
• Non-lamaste nginx sites in sites-enabled → "Existing nginx sites will be affected"
• Port 3100 in use (checked via ss) → "The panel may fail to start"
• Active UFW with existing rules → "Existing UFW firewall rules will be reset"

Phase 2: Installation Tasks

Six task groups run sequentially through Listr2:

Order	Task Group	Source	Key Operations
1	Hardening	tasks/harden.js	Swap file, UFW firewall, fail2ban, SSH hardening, system packages
2	Node.js	tasks/node.js	Check existing, add NodeSource repo, install, verify
3	mTLS	tasks/mtls.js	CA key + cert, client key + CSR, sign, PKCS12 bundle
4	nginx	tasks/nginx.js	Self-signed TLS cert, mTLS snippet, IP vhost, port-80 redirect, enable site, start
5	Panel	tasks/panel.js	System user, root-owned install dir + cert help page, pinned chisel + Authelia (binaries, units, accounts, ownership), deploy server + CLI + client + docs, config, systemd, lamaste-priv and wrappers, sudoers, start + health check
6	Gatekeeper	tasks/gatekeeper.js	Deploy gatekeeper (root-owned), state files, systemd unit, start

Task Implementation Details

Hardening (tasks/harden.js)

Swap file creation:

• Checks if swap is already active via swapon --show
• Creates 1 GB swap at /swapfile with fallocate, mkswap, swapon
• Adds to /etc/fstab if not already present
• Sets vm.swappiness=10 via sysctl (reduces swap aggressiveness)

UFW firewall:

• If UFW is already active, only adds missing port rules (22, 443, 9292)
• If inactive, sets defaults (deny incoming, allow outgoing), allows ports, enables
• Never resets an active firewall — preserves existing rules

fail2ban:

• Installs via apt-get, writes drop-in config at /etc/fail2ban/jail.d/lamaste.conf
• Configures SSH jail (5 attempts, 1 hour ban) and nginx-http-auth jail
• Skip guard: checks if config already exists with expected content and service is active

SSH hardening:

• Sets PasswordAuthentication no, PermitRootLogin prohibit-password, ChallengeResponseAuthentication no
• Uses write-validate-swap pattern: writes to temp file, validates with sshd -t -f, then moves into place
• Creates backup at /etc/ssh/sshd_config.pre-lamaste before first modification
• If validation fails, temp file is deleted and original config remains untouched

System dependencies:

• Runs apt-get update then installs curl, openssl, nginx, certbot, python3-certbot-nginx
• Stops nginx after installation (will be configured and started by the nginx task)
• Removes the default nginx site from sites-enabled

mTLS Certificates (tasks/mtls.js)

CA generation:

• 4096-bit RSA key at /etc/lamalibre/lamaste/pki/ca.key (mode 600)
• Self-signed CA certificate at /etc/lamalibre/lamaste/pki/ca.crt (mode 644) with 10-year validity
• Subject: CN=Lamaste CA, O=Lamaste

Client certificate:

• 4096-bit RSA key at /etc/lamalibre/lamaste/pki/client.key (mode 600)
• CSR signed by CA with 2-year validity
• Subject: CN=admin, O=Lamaste
• CSR is deleted after signing (no longer needed)

PKCS12 bundle:

• Combines client key + cert + CA cert into /etc/lamalibre/lamaste/pki/client.p12 (mode 600)
• Uses legacy algorithms (PBE-SHA1-3DES, sha1 MAC) for maximum browser compatibility — modern PKCS12 defaults are not supported by macOS Keychain Access
• Password generated via crypto.randomBytes(24).toString('base64url')
• Password saved to /etc/lamalibre/lamaste/pki/.p12-password (mode 600)

nginx Configuration (tasks/nginx.js)

Self-signed TLS certificate:

• 2048-bit RSA key for the IP-based vhost
• Includes subjectAltName=IP:<detected-ip> for browser compatibility
• 10-year validity — this cert is only for IP access, not public-facing

mTLS snippet:

• Written to /etc/nginx/snippets/lamalibre-lamaste-mtls.conf
• Contains two lines: ssl_client_certificate pointing to CA cert, and ssl_verify_client on
• Shared by the IP vhost and the domain panel vhost (after onboarding)

IP-based panel vhost:

• Listens on port 9292 with SSL
• Includes the mTLS snippet for client certificate enforcement
• Proxies all traffic to 127.0.0.1:3100 (Panel Server)
• WebSocket upgrade support for /api paths
• Custom error pages (495/496) serve a certificate help page for visitors without certs

Certificate help page (written by the panel task, and regenerated on every redeploy):

• Static HTML at /opt/lamalibre/lamaste/lamaste-server-ui/cert-help.html
• Styled with the same dark terminal aesthetic as the panel
• Shows step-by-step instructions for downloading and importing the client certificate
• Served by nginx when SSL client verification fails (error codes 495, 496)

Panel Deployment (tasks/panel.js)

System user:

• Creates lamaste user with --system --no-create-home --shell /usr/sbin/nologin
• Idempotent: checks if user exists first with id lamaste

Directory structure:

• /opt/lamalibre/lamaste/ — code (panel server, lamaste-server CLI, UI, docs, gatekeeper, cert help page), root-owned and read-only for lamaste. The lamaste-server CLI is run as root by administrators, so the panel must not be able to change it. A tree owned by anyone but root (earlier versions gave it to lamaste) is moved aside, every component is deployed fresh, and the old tree is removed.
• /etc/lamalibre/lamaste/ — configuration and state, owned by lamaste
• /var/www/lamaste/ — static site roots, lamaste:www-data, directories 2750 (setgid), files 0640

Chisel and Authelia (lib/relay-services.js, run on install and on every redeploy):

• Creates the lamaste-chisel group (and adds lamaste to it) and the lamaste-authelia system account (no login shell, no home)
• Installs Chisel 1.12.0 and Authelia 4.39.28 to /usr/local/bin (lib/binaries.js): downloaded from fixed release URLs, verified against the SHA-256 digests pinned in @lamalibre/lamaste (CHISEL_RELEASE, AUTHELIA_RELEASE) before anything is unpacked, staged in a mkdtemp directory and renamed into place. A binary already at the pinned version is left alone; an Authelia newer than the pin is kept, never downgraded (its database may use a schema the pinned release cannot read)
• Writes /etc/systemd/system/chisel.service (User=nobody, Group=lamaste-chisel) and /etc/systemd/system/authelia.service (User=lamaste-authelia, UMask=027, Environment=X_AUTHELIA_CONFIG_FILTERS=template, ProtectSystem=strict with ReadWritePaths=/etc/authelia /var/log/authelia, SystemCallFilter=@system-service, empty CapabilityBoundingSet, NoNewPrivileges); both are enabled and started later by onboarding
• Generates the OpenID Connect issuer key /etc/authelia/oidc-issuer.pem if it is missing (lib/oidc-issuer-key.js): RSA 4096 generated in the installer process, written by a child process running as lamaste-authelia (wx, 0600, renamed into place) so root never writes through /etc/authelia. The panel references it from Authelia's configuration with a {{ secret "…" }} template expression — which is why the unit and lamaste-priv authelia-totp set the template configuration filter — and can never read it. A key owned by anyone else is replaced; one owned by the Authelia account is kept (its mode fixed through a descriptor if it drifted)
• Sets ownership (lib/ownership.js): /var/www/lamaste lamaste:www-data 2750; /etc/authelia lamaste:lamaste-authelia 2770 (setgid) with configuration.yml 0640, users.yml 0660, .secrets.json 0600 (lamaste), db.sqlite3* and notifications.txt lamaste-authelia 0600; /var/log/authelia lamaste-authelia 0750; chisel-server.key (if present) lamaste:lamaste-chisel 0640; the PKI directory lamaste:lamaste (the panel is the CA)

Every write root makes in a directory lamaste can write to (its config directory, the web root, /etc/authelia) avoids following symlinks the panel could have planted: new files are created O_EXCL | O_NOFOLLOW and renamed into place, ownership is changed through the file descriptor, recursive changes use chown -R -P / rm -rf --one-file-system.

Server deployment:

• Copies package.json and src/ from vendor/lamaste-serverd/
• Runs npm install --production --ignore-scripts in the deployment directory (root-owned)

Client deployment:

• Prefers pre-built dist/ directory from vendor (avoids Vite build on low-RAM VPS)
• Falls back to building from source in a fresh mkdtemp directory if no pre-built dist exists
• Only the dist/ output is deployed to the lamaste-server-ui directory

Configuration:

• Writes /etc/lamalibre/lamaste/panel.json with detected IP, directory paths, and onboarding.status: "FRESH"
• On re-run: merges with existing config, preserving user/onboarding state
• File mode 0640, owned by lamaste:lamaste, written as a fresh file renamed into place

Systemd service:

• Unit file at /etc/systemd/system/lamalibre-lamaste-serverd.service
• Runs as the lamaste user with SupplementaryGroups=lamaste-chisel, ProtectHome=true, PrivateTmp=true, ReadWritePaths=/etc/lamalibre/lamaste /var/www/lamaste
• NoNewPrivileges is omitted: the panel runs the fixed sudo commands below
• Restart on failure with 5-second delay

Root-owned programs (lib/wrappers.js), installed before the sudoers file:

• /usr/local/sbin/lamaste-priv (Node.js, syntax-checked with node --check), /usr/local/sbin/lamaste-certbot and /usr/local/sbin/lamaste-cert-info (bash, checked with bash -n), installed root:root 0755
• The retired lamaste-sign-csr and lamaste-pki-rename are removed
• See Security Model for what each accepts

Sudoers rules:

• /etc/sudoers.d/lamaste contains no wildcard: only fixed systemctl command lines (nginx; chisel including try-restart, enable, disable; authelia; certbot.timer; the panel and gatekeeper services), nginx -t, and the three programs above
• Installed atomically: written as /etc/sudoers.d/lamaste.lamaste-new (sudo ignores files with a dot in their name), checked with visudo -c, then renamed into place — an invalid file is never live and the previous rules stay in force
• No blanket root access

Health check:

• After starting the service, waits 3 seconds, checks systemctl is-active
• Sends HTTP request to http://127.0.0.1:3100/api/health
• If either check fails, captures recent journal logs and reports them in the error message

Idempotency

The installer is designed to be safely re-run on the same machine. Every task group implements skip guards that detect existing state:

Task	Skip Condition	Behavior
Swap creation	swapon --show returns data	Skip silently
UFW firewall	All required ports already allowed and active	Skip silently
fail2ban	Config exists with expected content and service is active	Skip silently
SSH hardening	All settings already correct in sshd_config	Skip silently
Node.js install	node --version returns v20+	Skip NodeSource + apt-get
mTLS certs	ca.key and client.p12 both exist	Skip entire group, read existing password
Panel config	panel.json exists	Merge instead of overwrite
System user	id lamaste succeeds	Skip useradd

The mTLS certificate skip guard is especially important: regenerating certificates would invalidate the admin's already-imported client certificate, locking them out of the panel.

Redeploy Mode

When the installer detects an existing Lamaste installation (/etc/lamalibre/lamaste/panel.json exists) and the --force-full flag is not set, it enters redeploy mode instead of running the full installation.

Redeploy mode stops the panel and gatekeeper, secures the install directory (a non-root-owned tree is moved aside and removed at the end), redeploys the panel server, lamaste-server CLI, UI, docs, gatekeeper and cert help page, merges panel.json, runs the same Chisel/Authelia step as a fresh install (stopping a running Authelia while its files change hands), rewrites the panel's systemd unit, the root-owned programs and the sudoers rules, ensures the port-80 redirect, then restarts Chisel if its binary or unit changed, starts Authelia and the gatekeeper if they were running, and restarts the panel. It does not touch OS hardening, mTLS certificates or the panel's vhosts. The panel's self-update (sudo lamaste-priv self-update <version>) runs this path as root, so it never writes through a path the lamaste user controls.

This provides a fast upgrade path: re-running npx @lamalibre/create-lamaste on an existing installation updates the code and the pinned services while preserving all configuration and certificates. Use --force-full to bypass this and run the complete installer.

The redeploy logic lives in tasks/redeploy.js, with shared systemd unit and sudoers content generators in lib/service-config.js.

Vendor Bundling

The create-lamaste package ships with the lamalibre-lamaste-serverd and lamaste-server-ui code bundled in a vendor/ directory. This is necessary because:

1. The installer runs on a fresh VPS with no access to the monorepo
2. npm install on the server only installs the create-lamaste package
3. The vendor directory contains the exact code that was built and tested

The vendor directory structure:

packages/create-lamaste/vendor/
├── lamaste-serverd/
│   ├── package.json
│   └── src/                    ← Server source code
└── lamaste-server-ui/
    └── dist/                   ← Pre-built Vite output (preferred)
        ├── index.html
        └── assets/

When dist/ contains a pre-built index.html, the installer copies it directly. This avoids running vite build on the VPS, which can OOM-kill on a 512 MB droplet.

Error Handling

The installer follows a fail-fast philosophy with safe re-run guarantees:

At the orchestrator level:

• exitOnError: true on both Listr2 task groups — any failure stops the entire pipeline
• The error handler prints a formatted box with the error message and a "You can safely re-run this installer to retry" note
• Exit code 1 on any failure

At the task level:

• Every execa call includes descriptive error messages that explain what failed and suggest recovery steps
• Network errors (apt-get, curl, npm) include "Check your internet connection" hints
• Validation errors (sshd, nginx, sudoers) clean up temp files before throwing

At the subtask level:

• subtask.output provides real-time progress for long-running operations (e.g., "Downloading NodeSource setup script...")
• rendererOptions: { persistentOutput: true } keeps the last status visible in the terminal

CLI Flags

Flag	Purpose
--help, -h	Print help message describing what the installer does and exit
--yes, -y	Skip the confirmation prompt (for automated installs)
--skip-harden	Skip OS hardening tasks (swap, UFW, fail2ban, SSH)
--dev	Accept private/non-routable IP addresses (for VM testing)
--force-full	Run the full installation even on existing installs (bypasses redeploy mode)
--uninstall	Print manual removal guide and exit

Shared Context Object

All tasks share a ctx object that accumulates state through the pipeline:

const ctx = {
  ip: null, // Detected public IP
  osRelease: null, // { id, versionId, prettyName }
  skipHarden: false, // --skip-harden flag
  nodeAlreadyInstalled: false, // Skip Node.js install if v20+
  nodeVersion: null, // e.g., "v20.11.1"
  npmVersion: null, // e.g., "10.2.4"
  p12Password: null, // Generated PKCS12 password
  pkiDir: '/etc/lamalibre/lamaste/pki', // Certificate directory
  configDir: '/etc/lamalibre/lamaste', // Configuration directory
  installDir: '/opt/lamalibre/lamaste', // Deployment directory
};

Key Files

File	Role
packages/provisioners/server/bin/create-lamaste.js	CLI entry point (#!/usr/bin/env node)
packages/provisioners/server/src/index.js	Main orchestrator with Listr2 pipeline
packages/provisioners/server/src/tasks/harden.js	OS hardening subtasks
packages/provisioners/server/src/tasks/node.js	Node.js 20 installation subtasks
packages/provisioners/server/src/tasks/mtls.js	mTLS certificate generation subtasks
packages/provisioners/server/src/tasks/nginx.js	nginx IP-based configuration subtasks
packages/provisioners/server/src/tasks/panel.js	Panel deployment subtasks
packages/provisioners/server/src/tasks/gatekeeper.js	Gatekeeper deployment subtasks
packages/provisioners/server/src/tasks/redeploy.js	Redeployment (upgrade and self-update) subtasks
packages/provisioners/server/src/lib/relay-services.js	Accounts, pinned binaries, units and ownership for chisel/Authelia
packages/provisioners/server/src/lib/binaries.js	Verified install of the pinned chisel and Authelia releases
packages/provisioners/server/src/lib/accounts.js	lamaste-chisel group and lamaste-authelia account
packages/provisioners/server/src/lib/ownership.js	Symlink-safe root writes, directory ownership migrations
packages/provisioners/server/src/lib/wrappers.js	Installs the root-owned programs and the sudoers file
packages/provisioners/server/src/lib/env.js	OS detection, IP detection, root check
packages/provisioners/server/src/lib/secrets.js	crypto.randomBytes wrappers
packages/provisioners/server/src/lib/summary.js	Post-install summary box printer
packages/provisioners/server/src/lib/cert-help-page.js	HTML help page generator
packages/provisioners/server/src/lib/service-config.js	Systemd unit + sudoers content generators
packages/provisioners/server/scripts/lamaste-priv	Root helper: panel vhosts (allow-listed), Authelia TOTP, self-update
packages/provisioners/server/scripts/lamaste-certbot, lamaste-cert-info	Validating certbot / certificate-read wrappers

Confirmation Banner

Between environment checks and installation, the installer displays a confirmation banner. This is the only user interaction point (unless --yes is passed).

The banner:

• Shows a formatted box listing all system modifications that will be made
• Displays detection warnings below the box (existing Lamaste install, UFW rules, port conflicts, existing nginx sites)
• Waits for the user to press Enter or Ctrl+C

┌─────────────────────────────────────────────────────────────┐
│  Lamaste Installer                                          │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  This will install Lamaste on this machine.                │
│                                                             │
│  The following changes will be made:                         │
│                                                             │
│    • Reset UFW firewall (allow ports 22, 443, 9292 only)    │
│    • Harden SSH (disable password authentication)           │
│    • Install fail2ban, Node.js 20, nginx, certbot           │
│    • Generate mTLS certificates for browser access          │
│    • Create lamaste user and systemd service               │
│    • Deploy panel to /opt/lamalibre/lamaste/                         │
│                                                             │
│  Designed for a fresh Ubuntu 24.04 droplet.                  │
│                                                             │
└─────────────────────────────────────────────────────────────┘

  ! An existing Lamaste installation was detected (onboarding: COMPLETED).
    Re-running will update the installation but preserve your configuration.
  ! Existing UFW firewall rules (6 rules) will be reset.

Warning messages are only shown when relevant conditions are detected. On a fresh droplet with no existing state, no warnings appear.

Post-Install Summary

After all tasks complete, printSummary() reads the saved PKCS12 password and displays a formatted box with everything the user needs:

1. SCP command to download the client certificate: scp root@<ip>:/etc/lamalibre/lamaste/pki/client.p12 .
2. Import instructions for macOS, Linux, and Windows browsers
3. Certificate password (highlighted in yellow for visibility)
4. Panel URL: https://<ip>:9292
5. Reassurance that they can disconnect from SSH

The summary box uses dynamic width calculation, stripping ANSI color codes to measure actual character widths, and builds a Unicode box-drawing border around the content.

Listr2 Rendering

The installer uses Listr2's default renderer with collapseSubtasks: false, which means all subtask output remains visible as the installer progresses. Each subtask uses rendererOptions: { persistentOutput: true } to keep the final status line visible after the subtask completes.

The rendering structure looks like this during execution:

✔ Checking environment
  ✔ Verifying root access
  ✔ Detecting operating system [Ubuntu 24.04.1 LTS]
  ✔ Detecting IP address [203.0.113.42]
◼ Hardening operating system
  ✔ Creating swap file [Swap file created and activated]
  ◼ Configuring UFW firewall [Allowing ports 22, 443, 9292...]
  ◼ Installing and configuring fail2ban
  ◼ Hardening SSH configuration
  ◼ Installing system dependencies

This gives the operator clear visibility into what is happening, which is important when modifying a production server.

Design Decisions

Why zero prompts?

The installer collects no input. Domain, email, and all other configuration happen through the browser-based onboarding wizard after the panel is running. This separation means the installer can be fully automated (--yes flag) and the user gets a graphical interface for the complex decisions.

Why Listr2?

Listr2 provides structured task output with progress indicators, persistent output lines, and nested subtask rendering. This makes it clear what the installer is doing at every step — important for a script that modifies the OS.

Why vendor bundling instead of npm workspace install?

The installer runs via npx on a fresh server. npx installs only the create-lamaste package, not the full monorepo. The vendor approach ships a self-contained bundle with all code needed, avoiding network-dependent monorepo installs on the target server.

Why PBE-SHA1-3DES for PKCS12?

Modern OpenSSL defaults produce PKCS12 bundles that macOS Keychain Access cannot import. The legacy algorithm flags (-keypbe PBE-SHA1-3DES -certpbe PBE-SHA1-3DES -macalg sha1) ensure compatibility across macOS, Windows, and Linux browsers. Security of the PKCS12 bundle is not critical — it is a one-time transport mechanism protected by a random password.