Ai Airlock

Guided Cloudflare Installation

This path configures a public Linux VPS with a Cloudflare-managed domain. The installer checks Docker, discovers the public IP, configures DNS and wildcard TLS, writes .env, and starts the stack.

1. Prepare Cloudflare

Buy or transfer a domain to Cloudflare. Set DOMAIN to the zone apex, such as example.com, not a nested name such as airlock.example.com.

Cloudflare Universal SSL covers the zone apex and one wildcard level: example.com and *.example.com. Airlock creates app subdomains under DOMAIN. If DOMAIN=airlock.example.com, an app would use app.airlock.example.com, which Universal SSL does not cover. A nested DOMAIN requires a certificate that explicitly covers *.airlock.example.com.

Create an API token scoped to the domain’s zone with these permissions:

  • Zone:DNS:Edit
  • Zone:Zone:Read

The installer uses the token to find the zone, create the apex and wildcard DNS records, and issue a DNS-01 wildcard certificate.

Cloudflare API token policy with DNS Edit and Zone Read permissions for one domain
Scope the token to the Airlock domain, then enable DNS Edit and Zone Read.

1.5 Optional: Host without a public IP

Use Cloudflare Tunnel when Airlock runs behind NAT, on a home server, or on any machine that cannot accept public inbound traffic.

  1. In Cloudflare, open Zero Trust and activate the free plan for the account.
  2. Open Networks > Connectors > Add a tunnel.
  3. Select Cloudflared, name the tunnel, then select Docker as the connector type.
  4. Copy the generated docker run command. The installer extracts the tunnel token from it.
Cloudflare tunnel connector page with Docker selected and the generated docker run command
Copy the Docker command, but do not share it: it contains the tunnel token.

  1. Run the installer with Cloudflare Tunnel forced, then enter the domain and paste the copied command when prompted:

    curl -fsSL https://raw.githubusercontent.com/airlockrun/airlock/v0.4.0/install.sh | bash -s -- --cloudflared

    The installer extracts the tunnel token, configures the private Caddy and Cloudflared services, and starts Airlock. After Airlock starts, Cloudflare waits for the connector before allowing routes to be added.

  2. In the tunnel’s Public Hostnames settings, add these routes, each pointing to http://caddy:80

    • DOMAIN
    • *.DOMAIN
Cloudflare Public Hostname form configured with a wildcard subdomain for the Airlock domain
Add the wildcard hostname first: enter `*.DOMAIN` and choose the Cloudflare-managed domain.
Cloudflare Public Hostname form configured with the Airlock apex domain and service caddy port 80
Add the apex hostname next: enter `DOMAIN`, leave Path empty, and set the service to `http://caddy:80`.
Cloudflare tunnel published application routes showing the apex domain and wildcard domain routed to caddy port 80
Both the apex and wildcard routes must point to `http://caddy:80`.
  1. Open DNS > Records. Adding the apex tunnel route creates the apex DNS record, but the wildcard tunnel route does not create the wildcard DNS record. Add a proxied wildcard CNAME record:
    • Name: *
    • Target: Copy the target from the auto-created DOMAIN tunnel record. It looks like <tunnel-id>.cfargotunnel.com.
    • Proxy status: Proxied

Cloudflare can display the existing apex record as type Tunnel. Its target is the value to copy into the wildcard CNAME. Do not point the wildcard record at DOMAIN; point it at the same tunnel target.

Cloudflare DNS record form adding a proxied wildcard CNAME record whose target is the Cloudflare tunnel hostname
Create the wildcard CNAME with the same tunnel target as the apex record, then keep it proxied.

Cloudflare terminates TLS at its edge. Airlock’s Caddy container remains private on the Docker network, and Cloudflared is the only public ingress.

2. Prepare the VPS

Complete the Linux VPS prerequisites. Use a Linux VPS with at least 2 vCPUs, 4 GB RAM, 40 GB of disk space, and a user with sudo access.

3. Run the installer

curl -fsSL https://raw.githubusercontent.com/airlockrun/airlock/v0.4.0/install.sh | bash

Answer the prompts with the Cloudflare domain and API token. The installer checks whether the domain resolves to the VPS public IP, offers Cloudflare DNS and wildcard TLS configuration, then asks whether to bundle Postgres and object storage.

4. Activate Airlock

After the installer health check completes, follow the activation guide to create the first administrator account and configure providers, defaults, and optional Telegram access.

Keep the generated .env private. It contains encryption keys, database credentials, and the Cloudflare API token.

Upgrade

Run upgrades from the checkout created by the installer:

cd ~/airlock
./upgrade.sh

The upgrade retains .env, applies database migrations at startup, and restarts the stack. Back up Postgres before a production upgrade.