Friends keep asking how my homelab works, so I wrote it all down, starting from zero. Four NixOS machines run about 150 containers behind one Traefik front door, and with WireGuard and my own Headscal...

Use Jev with Traefik Hub to block risky AI prompts, apply policies, and meter API calls using confidence-based decisions.

A complete step-by-step guide to deploy and host the open-source **Paperclip agent orchestration platform** on an **Oracle Cloud Infrastructure (OCI) ARM64 VPS** using **Coolify, Docker Compose, Traefik, Let's Encrypt SSL, PostgreSQL, and OpenRouter**. > **Security note:** Replace all example passwords, secrets, API keys, and domain names with your own values. Never commit secrets or API keys to Git. ## Table of Contents 1. Architecture Overview 2. Prerequisites 3. Network & Firewall Configuration * DNS Configuration * OCI VCN Security Rules * Ubuntu Host Firewall 4. Generate Application Secrets 5. Coolify Service Configuration * Create Docker Compose Resource * Environment Variables * Domain & Port Mapping * Deploy 6. Bootstrap the First Admin Account 7. Complete Initial Onboarding 8. Configure OpenRouter 9. Verification 10. Troubleshooting 11. Security & Production Checklist # Architecture Overview The deployment consists of the following components: Component | Technology ---|--- Host | Oracle Cloud Infrastructure (OCI) Ampere A1 ARM64 VPS Operating System | Ubuntu Deployment/Orchestration | Coolify Container Runtime | Docker Reverse Proxy | Traefik SSL | Let's Encrypt Database | PostgreSQL 17 Alpine Application | `ghcr.io/paperclipai/paperclip:latest` Domain | `https://paperclip.arpann8n.qzz.io` AI Gateway | OpenRouter API Agent Runtime | OpenCode ### Request flow User Browser | | HTTPS :443 v Oracle Cloud VPS | v Coolify / Traefik | | HTTPS termination + routing v Paperclip :3100 | +--------------------+ | | v v PostgreSQL 17 OpenRouter API | | v v Persistent Data AI Model Provider # Prerequisites Before starting, make sure you have: * An Oracle Cloud account. * An OCI Ampere A1 ARM64 VPS. * Ubuntu installed on the VPS. * Coolify installed and accessible. * A domain/subdomain you control. * DNS access for that domain. * An OpenRouter account and API key. * SSH access to the VPS. * Ports **80** and **443** available for web traffic. # 1. Network & Firewall Configuration ## A. DNS Configuration Open your DNS provider dashboard and create an **A record**. Setting | Value ---|--- Name / Host | `paperclip` Type | `A` Target / Value | Your Oracle Cloud VPS public IPv4 address TTL | Automatic or `300` seconds The resulting hostname should resolve to your VPS, for example: paperclip.example.com This guide uses: https://yourDomain.com ### Verify DNS From your local machine: nslookup yourDomain.com or: dig yourDomain.com The returned IP should match your Oracle Cloud VPS public IPv4 address. ## B. Oracle Cloud VCN Security Rules Log in to the Oracle Cloud Console. Navigate to: Networking → Virtual Cloud Networks → Your VCN → Security Lists → Default Security List Under **Ingress Rules** , click **Add Ingress Rules**. Create an inbound rule with: Field | Value ---|--- Source CIDR | `0.0.0.0/0` Protocol | TCP Destination Port Range | `80,443` Description | Allow HTTP and HTTPS web traffic Save the rule. ### Why both ports? * **80/tcp** is commonly used by Let's Encrypt HTTP-01 validation and HTTP-to-HTTPS redirects. * **443/tcp** is used for HTTPS traffic. ## C. Host Firewall (Ubuntu IPTables) Some Oracle Ubuntu images may have host-level firewall rules that prevent incoming HTTP/HTTPS traffic. Allow ports 80 and 443: # Allow HTTPS (443) at the top of the INPUT chain sudo iptables -I INPUT 1 -p tcp --dport 443 -j ACCEPT # Allow HTTP (80) at the top of the INPUT chain sudo iptables -I INPUT 1 -p tcp --dport 80 -j ACCEPT Install persistent firewall-rule support: sudo apt-get update sudo apt-get install -y iptables-persistent netfilter-persistent Save the rules: sudo netfilter-persistent save Verify: sudo iptables -L INPUT -n --line-numbers You should see ports **80** and **443** with target `ACCEPT`, preferably before any broad `REJECT` or `DROP` rule. > **Important:** Firewall configuration can differ between Ubuntu images and OCI networking setups. Review existing rules before changing them. # 2. Generate Application Secrets Generate a secure 32-byte hexadecimal secret on the VPS: openssl rand -hex 32 Example output: 9b7c0f...64-character-secret...e21a Save the complete 64-character value securely. This value will be used as: BETTER_AUTH_SECRET Do not publish it or commit it to Git. # 3. Coolify Service Configuration ## A. Create Docker Compose Resource Open your **Coolify Dashboard**. Navigate to: Project → + New → Docker Compose Paste the following Docker Compose configuration: version: '3.8' services: db: image: postgres:17-alpine restart: unless-stopped environment: POSTGRES_DB: paperclip POSTGRES_USER: paperclip POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:-postgresSecurePass123} volumes: - pgdata:/var/lib/postgresql/data healthcheck: test: ["CMD-SHELL", "pg_isready -U paperclip -d paperclip"] interval: 5s timeout: 5s retries: 5 paperclip: image: ghcr.io/paperclipai/paperclip:latest restart: unless-stopped depends_on: db: condition: service_healthy environment: NODE_ENV: production PORT: "3100" SERVE_UI: "true" HOST: "0.0.0.0" PAPERCLIP_DEPLOYMENT_MODE: "authenticated" PAPERCLIP_DEPLOYMENT_EXPOSURE: "public" PAPERCLIP_PUBLIC_URL: "https://yourDomain.com" BETTER_AUTH_SECRET: "${BETTER_AUTH_SECRET}" DATABASE_URL: "postgres://paperclip:${POSTGRES_PASSWORD:-postgresSecurePass123}@db:5432/paperclip" PAPERCLIP_SECRETS_MASTER_KEY_FILE: "/paperclip/instances/default/secrets/master.key" OPENROUTER_API_KEY: "${OPENROUTER_API_KEY}" volumes: - paperclip-data:/paperclip volumes: pgdata: paperclip-data: ### Important If you use a different domain, update: PAPERCLIP_PUBLIC_URL: "https://yourDomain.com" to your actual public URL. For example: PAPERCLIP_PUBLIC_URL: "https://yourDomain.com" ## B. Add Environment Variables In Coolify, open the stack's **Environment Variables** section. Add: POSTGRES_PASSWORD=<A-STRONG-RANDOM-PASSWORD> BETTER_AUTH_SECRET=<OUTPUT-FROM-openssl-rand-hex-32> OPENROUTER_API_KEY=sk-or-v1-xxxxxxxxxxxxxxxxxxxx ### Generate a strong PostgreSQL password You can generate one with: openssl rand -base64 32 Use the generated value for: POSTGRES_PASSWORD ### Environment-variable example Do **not** copy these example values into production: POSTGRES_PASSWORD=replace-with-your-own-password BETTER_AUTH_SECRET=replace-with-your-own-secret OPENROUTER_API_KEY=sk-or-v1-replace-with-your-own-key ## C. Configure Domain & Port Mapping Open the **Domains** tab in the Coolify service view. Click: + Add Domain Configure: Setting | Value ---|--- Service | `paperclip` Image | `ghcr.io/paperclipai/paperclip:latest` Protocol | `https` Domain | `paperclip.arpann8n.qzz.io` Port | `3100` Path | Leave empty Click **Save**. Coolify/Traefik will use this configuration to route HTTPS traffic to Paperclip's internal port `3100`. ## D. Deploy the Stack Click **Deploy** in the top-right corner of Coolify. Coolify should: 1. Pull the required container images. 2. Start PostgreSQL. 3. Wait for the PostgreSQL health check. 4. Start Paperclip. 5. Apply the application's database setup/migrations as required by the image. 6. Configure Traefik routing. 7. Request/provision a Let's Encrypt certificate. 8. Serve Paperclip over HTTPS. After deployment, visit: https://yourDomain.com # 4. Bootstrapping First Admin (CEO) Account Because the instance is configured with authenticated public deployment mode, browser-based self-registration is disabled. A one-time bootstrap link must be generated from inside the Paperclip container. ## Open the Container Terminal In Coolify: Observe & troubleshoot → Terminal Select the: paperclip container. ## Fix Internal Volume Permissions Run: chown -R node:node /paperclip chmod -R 700 /paperclip/instances/default/secrets Then generate the CEO bootstrap URL: su -s /bin/sh node -c "pnpm paperclipai auth bootstrap-ceo" The command should output a single-use URL similar to: https://yourDomain.com/auth/claim?token=... Open that URL in your browser. Complete the administrator registration: * Name * Email * Password > Treat the bootstrap URL as a credential. Do not post it publicly or commit it to source control. # 5. Completing Initial Onboarding During the Paperclip onboarding wizard, you may see a screen asking you to connect a model with **Claude** and **OpenAI** buttons. ### Do not enter the OpenRouter API key into those fields Those fields may perform provider-specific API validation against Anthropic/OpenAI endpoints. An OpenRouter key is not necessarily valid for those direct-provider checks. Instead: Use subscription or skip that step if the UI provides a skip option. Continue through the remaining onboarding steps until you reach the main Paperclip workspace dashboard. # 6. OpenRouter Integration & Agent Configuration Headless container environments may not provide the terminal capabilities required by some CLI-based agent runtimes. For this deployment, configure the CEO agent to use an **API-based OpenCode runtime** through OpenRouter. ## A. Store the OpenRouter API Key From the Paperclip workspace: Company name → Company Settings Alternatively, navigate to: /company/settings/secrets Click: + New secret Configure: Field | Value ---|--- Who provides the value? | Organization Type | Managed value Name | `OPENROUTER_API_KEY` Value | Your OpenRouter API key Key | `OPENROUTER_API_KEY` Your API key will normally look similar to: sk-or-v1-... Click **Save**. ## B. Bind the Secret to the CEO Agent In the left navigation: Agents → CEO → Secrets & variables Under: API ACCESS (NO ENV VAR) add: OPENROUTER_API_KEY Click: Save changes ## C. Set Runtime to OpenCode Open the CEO agent settings. Navigate to: Harness / Runtime Configure: Setting | Value ---|--- Adapter type | `OpenCode` Model | Your desired OpenRouter model slug Examples: openai/gpt-4o-mini or: anthropic/claude-3.5-sonnet or another model supported by your OpenRouter account and current Paperclip/OpenCode integration. > Model availability, names, pricing, and provider support can change. Use a currently supported model slug from OpenRouter/Paperclip rather than assuming an older model name will remain available. Click: Test again or: Verify You should receive a successful connection result. Then click: Save changes ## Clear Any Existing Error Banner If the CEO agent still shows an old failure banner: Overview → Clear error This clears the previous runtime error state after the configuration has been corrected. # 7. Verification Navigate to: Tasks → Paperclip onboarding (SKO-1) Send a test message such as: Hello, please proceed with the onboarding plan. The CEO agent should process the request through the configured OpenCode runtime and OpenRouter API. A successful flow should look like: Paperclip Task | v CEO Agent | v OpenCode Adapter | v OpenRouter API | v Selected AI Model | v Response | v Paperclip Task # Troubleshooting ## 1. Domain does not open Check DNS: nslookup paperclip.arpann8n.qzz.io Confirm that it resolves to the correct OCI public IP. Then verify OCI ingress rules allow: TCP 80 TCP 443 Also inspect the Ubuntu firewall: sudo iptables -L INPUT -n --line-numbers ## 2. Let's Encrypt certificate fails Check all of the following: * DNS points to the correct public IP. * OCI VCN allows TCP 80 and 443. * Ubuntu firewall allows TCP 80 and 443. * No other service is blocking Traefik. * The domain is publicly resolvable. * The Coolify/Traefik domain configuration is correct. HTTP port 80 can be particularly important when using HTTP-01 certificate validation. ## 3. Paperclip cannot connect to PostgreSQL Check the PostgreSQL container: docker ps Inspect logs through Coolify or Docker: docker logs <postgres-container> The PostgreSQL health check is: pg_isready -U paperclip -d paperclip Make sure the application and database use the same: POSTGRES_PASSWORD ## 4. CEO bootstrap command fails Inside the Paperclip container, check the volume permissions: ls -la /paperclip ls -la /paperclip/instances/default ls -la /paperclip/instances/default/secrets Then run: chown -R node:node /paperclip chmod -R 700 /paperclip/instances/default/secrets Retry: su -s /bin/sh node -c "pnpm paperclipai auth bootstrap-ceo" ## 5. Agent reports terminal/ACP failure If the agent reports a terminal or ACP access failure, verify that the CEO agent is not configured to use a CLI runtime that requires an interactive terminal. Check: Agents → CEO → Harness / Runtime Use: Adapter type: OpenCode and ensure: OPENROUTER_API_KEY is available to the agent. ## 6. OpenRouter authentication fails Verify the secret exists at the company level: Company Settings → Secrets Confirm the key is: OPENROUTER_API_KEY Then verify it is bound to: CEO → Secrets & variables Do not confuse: OPENROUTER_API_KEY with provider-specific credentials such as: ANTHROPIC_API_KEY OPENAI_API_KEY # Security & Production Checklist Before exposing the deployment to the public internet, review the following. ## Secrets * [ ] `POSTGRES_PASSWORD` is strong and unique. * [ ] `BETTER_AUTH_SECRET` was generated randomly. * [ ] OpenRouter API key is stored as a secret. * [ ] Secrets are not committed to Git. * [ ] Example secrets in documentation are clearly marked as placeholders. ## Networking * [ ] OCI ingress allows only the ports actually required. * [ ] TCP 80 is available if required for certificate validation/redirects. * [ ] TCP 443 is available for HTTPS. * [ ] PostgreSQL port `5432` is **not** publicly exposed. * [ ] Paperclip port `3100` is **not** publicly exposed directly when Traefik is handling ingress. ## Application * [ ] Paperclip uses authenticated deployment mode. * [ ] A strong administrator password is used. * [ ] The bootstrap URL is treated as single-use and confidential. * [ ] The correct public URL is configured. * [ ] Persistent volumes are enabled. ## Database * [ ] PostgreSQL data is stored in a persistent Docker volume. * [ ] Database backups are configured separately. * [ ] Database credentials are not hard-coded in Git. * [ ] PostgreSQL is reachable only from the internal Docker network. ## OpenRouter * [ ] API key is stored as a secret. * [ ] API spending/usage limits are configured according to your needs. * [ ] Only required agents receive access to the API secret. * [ ] The selected model is currently available and supported. # Useful Commands ## Generate a secure auth secret openssl rand -hex 32 ## Generate a database password openssl rand -base64 32 ## Check DNS nslookup paperclip.arpann8n.qzz.io ## Check firewall rules sudo iptables -L INPUT -n --line-numbers ## Allow HTTP sudo iptables -I INPUT 1 -p tcp --dport 80 -j ACCEPT ## Allow HTTPS sudo iptables -I INPUT 1 -p tcp --dport 443 -j ACCEPT ## Save firewall rules sudo netfilter-persistent save ## Check listening ports sudo ss -tulpn # Deployment Summary The complete deployment process is: 1. Create OCI ARM64 Ubuntu VPS ↓ 2. Point DNS A record to VPS ↓ 3. Allow TCP 80/443 in OCI VCN ↓ 4. Allow TCP 80/443 on Ubuntu firewall ↓ 5. Generate BETTER_AUTH_SECRET ↓ 6. Create Docker Compose stack in Coolify ↓ 7. Configure PostgreSQL + Paperclip ↓ 8. Add Coolify environment variables ↓ 9. Configure Paperclip domain → port 3100 ↓ 10. Deploy stack ↓ 11. Generate CEO bootstrap URL ↓ 12. Create administrator account ↓ 13. Complete onboarding ↓ 14. Create OPENROUTER_API_KEY secret ↓ 15. Bind secret to CEO agent ↓ 16. Configure OpenCode runtime ↓ 17. Select OpenRouter model ↓ 18. Verify connection ↓ 19. Send test task ↓ 20. Paperclip agent responds through OpenRouter # Final Result After completing the guide, the deployment should provide: * Public HTTPS access to Paperclip. * Automatic TLS termination through Coolify/Traefik. * Persistent PostgreSQL storage. * Persistent Paperclip application data. * Authenticated Paperclip access. * A bootstrapped CEO/admin account. * OpenRouter-backed AI inference. * OpenCode-based agent execution. * An ARM64-compatible deployment suitable for an OCI Ampere A1 VPS. ## Important Notes This guide is based on the configuration described in the deployment procedure. Paperclip, Coolify, OpenRouter, Docker images, model availability, and their configuration interfaces can change over time. Before production use, verify the current Paperclip and OpenRouter documentation for: * Current environment variables. * Supported runtimes/adapters. * Current model identifiers. * Authentication/bootstrap commands. * API requirements. * ARM64 image availability. * Backup and upgrade procedures. Never expose database credentials, authentication secrets, bootstrap URLs, or API keys in public repositories, screenshots, logs, or issue trackers.

Netflix, Spotify and Google Photos in one – only on your own server and without a monthly fee:...

Typebot is an open-source, visually-driven conversational form and chatbot builder. It serves as a self-hosted alternative to hosted form and chatbot builders, giving you full data ownership and control over integrations and embedding. This guide deploys Typebot on a Linux server using Docker Compose with PostgreSQL, Redis, and Traefik for reverse proxy and TLS termination. By the end, you'll have a working Typebot instance with a published bot embedded on a sample page. ## Prerequisites Before you begin, you need to: * Have access to a Linux-based server as a non-root user with `sudo` privileges. * Install Docker and Docker Compose. * Configure two domain A records pointing to your server, such as `builder.example.com` and `viewer.example.com`. * Have an email address for Let's Encrypt certificate registration. ## Set Up the Directory Structure and Environment Variables To prevent data loss during container restarts or updates, the deployment relies on host-mounted volumes for PostgreSQL, Redis, and TLS certificates. Docker Compose reads secrets, URLs, and credentials from a `.env` file in the project directory and substitutes them into the service definitions at startup. **1. Create a project directory for the Typebot deployment:** $ mkdir -p ~/typebot/{pgdata,redisdata,letsencrypt,data} The command creates four subdirectories: * `pgdata`: Persists PostgreSQL database files. * `redisdata`: Stores Redis data used by Typebot's Redis-backed features, such as sign-in rate limiting and media uploads. * `letsencrypt`: Stores Traefik ACME certificates for automatic HTTPS renewal. * `data`: Stores Mailpit local email data. **2. Navigate to the project directory:** $ cd ~/typebot **3. Generate a strong random encryption secret that is used to encrypt sensitive data such as credentials and bot content:** $ openssl rand -base64 24 Copy the output. Use this value for the `ENCRYPTION_SECRET` variable in the next steps when creating the `.env` file. > Store this value securely and never change it once the deployment starts handling real data. Typebot uses `ENCRYPTION_SECRET` to encrypt stored credentials, and rotating it makes any previously encrypted data unreadable. **4. Create a`.env` file to store the environment variables:** $ nano .env **5. Add the following variables:** DOMAIN_BUILDER=builder.example.com DOMAIN_VIEWER=viewer.example.com LETSENCRYPT_EMAIL=admin@example.com ENCRYPTION_SECRET=YOUR_GENERATED_SECRET POSTGRES_DB=typebot POSTGRES_USER=typebot POSTGRES_PASSWORD=STRONG_DATABASE_PASSWORD DATABASE_URL=postgresql://${POSTGRES_USER}:${POSTGRES_PASSWORD}@postgres:5432/${POSTGRES_DB} REDIS_URL=redis://redis:6379 NEXTAUTH_URL=https://${DOMAIN_BUILDER} NEXT_PUBLIC_VIEWER_URL=https://${DOMAIN_VIEWER} ADMIN_EMAIL=admin@example.com DEFAULT_WORKSPACE_PLAN=UNLIMITED DISABLE_SIGNUP=false SMTP_HOST=mailpit SMTP_PORT=1025 SMTP_SECURE=false NEXT_PUBLIC_SMTP_FROM="Typebot Notifications <notifications@example.com>" SMTP_IGNORE_TLS=true SMTP_USERNAME=YOUR_SMTP_USERNAME SMTP_PASSWORD=YOUR_SMTP_PASSWORD TYPEBOT_DEBUG=false AUTH_TRUST_HOST=true `DEFAULT_WORKSPACE_PLAN=UNLIMITED` applies the unlimited plan to every new workspace, not only the administrator's. Signup stays open until later in this guide, so anyone who registers during that window also receives an unlimited workspace. Replace the following: * `builder.example.com` and `viewer.example.com` with your actual domains pointing to the server. * `admin@example.com` with your email for Let's Encrypt and admin access. * `YOUR_GENERATED_SECRET` with the output from the openssl command. * `STRONG_DATABASE_PASSWORD` with a secure password for PostgreSQL. * `YOUR_SMTP_USERNAME` with your username. * `YOUR_SMTP_PASSWORD` with a strong, secure password for your mail. * `notifications@example.com` in `NEXT_PUBLIC_SMTP_FROM` with a sender address on your own domain. Save and close the file. ## Deploy with Docker Compose Docker Compose orchestrates the full Typebot stack: Traefik for reverse proxy and HTTPS, PostgreSQL for persistent storage, Redis for sessions and caching, the Builder and Viewer services, and Mailpit for email. This configuration is adapted from the official Typebot Docker setup to use Traefik and persistent volumes. **1. Create the Docker Compose manifest:** $ nano docker-compose.yaml **2. Add the following content:** services: traefik: image: traefik:v3.7.8 container_name: traefik restart: unless-stopped command: - "--providers.docker=true" - "--providers.docker.exposedbydefault=false" - "--entrypoints.web.address=:80" - "--entrypoints.websecure.address=:443" - "--entrypoints.web.http.redirections.entrypoint.to=websecure" - "--entrypoints.web.http.redirections.entrypoint.scheme=https" - "--certificatesresolvers.letsencrypt.acme.httpchallenge=true" - "--certificatesresolvers.letsencrypt.acme.httpchallenge.entrypoint=web" - "--certificatesresolvers.letsencrypt.acme.email=${LETSENCRYPT_EMAIL}" - "--certificatesresolvers.letsencrypt.acme.storage=/letsencrypt/acme.json" ports: - "80:80" - "443:443" volumes: - "./letsencrypt:/letsencrypt" - "/var/run/docker.sock:/var/run/docker.sock:ro" postgres: image: postgres:16-alpine container_name: typebot-postgres restart: unless-stopped environment: POSTGRES_DB: ${POSTGRES_DB} POSTGRES_USER: ${POSTGRES_USER} POSTGRES_PASSWORD: ${POSTGRES_PASSWORD} volumes: - "./pgdata:/var/lib/postgresql/data" healthcheck: test: ["CMD", "pg_isready", "-d", "${POSTGRES_DB}", "-U", "${POSTGRES_USER}"] interval: 10s timeout: 5s retries: 5 redis: image: redis:8-alpine container_name: typebot-redis restart: unless-stopped command: ["redis-server", "--appendonly", "yes"] volumes: - "./redisdata:/data" healthcheck: test: ["CMD", "redis-cli", "ping"] interval: 10s timeout: 5s retries: 3 typebot-builder: image: baptistearno/typebot-builder:3.17.2 container_name: typebot-builder restart: unless-stopped env_file: - .env depends_on: postgres: condition: service_healthy redis: condition: service_healthy labels: - "traefik.enable=true" - "traefik.http.routers.typebot-builder.rule=Host(`${DOMAIN_BUILDER}`)" - "traefik.http.routers.typebot-builder.entrypoints=websecure" - "traefik.http.routers.typebot-builder.tls.certresolver=letsencrypt" - "traefik.http.services.typebot-builder.loadbalancer.server.port=3000" typebot-viewer: image: baptistearno/typebot-viewer:3.17.2 container_name: typebot-viewer restart: unless-stopped env_file: - .env depends_on: postgres: condition: service_healthy redis: condition: service_healthy labels: - "traefik.enable=true" - "traefik.http.routers.typebot-viewer.rule=Host(`${DOMAIN_VIEWER}`)" - "traefik.http.routers.typebot-viewer.entrypoints=websecure" - "traefik.http.routers.typebot-viewer.tls.certresolver=letsencrypt" - "traefik.http.services.typebot-viewer.loadbalancer.server.port=3000" mailpit: image: axllent/mailpit:v1.30.5 container_name: mailpit restart: unless-stopped ports: - "127.0.0.1:8025:8025" - "127.0.0.1:1025:1025" environment: MP_MAX_MESSAGES: 5000 MP_DATABASE: /data/mailpit.db MP_SMTP_AUTH_ACCEPT_ANY: 1 MP_SMTP_AUTH_ALLOW_INSECURE: 1 volumes: - ./data:/data * `traefik` * Acts as a reverse proxy and HTTPS termination layer for both the Builder and Viewer. * Listens on ports 80 and 443 for incoming web traffic and automatically redirects HTTP to HTTPS. * Requests and renews TLS certificates from Let's Encrypt using the email address defined in `LETSENCRYPT_EMAIL`. * Stores certificates persistently in the `./letsencrypt` directory. * `postgres` * Runs PostgreSQL 16 as the primary database to store all bots, user responses, workspaces, and configuration data. * Uses database credentials defined in the `.env` file. * Persists database files in the `./pgdata` directory on the host. * Includes a health check to ensure the database is fully initialized before the Typebot services start. * `redis` * Runs Redis 8 (Alpine), a required dependency for the Builder and Viewer services to start. * Supports sign-in rate limiting by IP and multiple media uploads on WhatsApp. * Persists data in the `./redisdata` directory. * Includes a health check to verify Redis is responsive. * `typebot-builder` * Runs the official Typebot Builder application (the visual editor). * Loads all configuration and secrets from the `.env` file. * Connects to both PostgreSQL and Redis, waiting for their health checks to pass before starting. * Registers itself with Traefik using Docker labels so it can be securely accessed via your builder domain. * `typebot-viewer` * Runs the official Typebot Viewer application (the public-facing bot runtime). * Loads all configuration and secrets from the `.env` file. * Connects to both PostgreSQL and Redis, waiting for their health checks to pass before starting. * Registers itself with Traefik using Docker labels so published bots can be accessed and embedded via your viewer domain. * `mailpit` * Runs Mailpit as a local email testing tool, bound to `127.0.0.1` so it is not exposed publicly. * Exposes the web UI on port `8025` and the SMTP service on port `1025` locally. * Stores email data in the `./data` directory. * Lets Typebot send sign-in verification codes to a local inbox instead of a real mailbox. * Lets you read messages in your local browser at `http://localhost:8025` via an SSH tunnel after deployment. > Mailpit only captures mail locally. It never delivers to a real inbox, so it is not a production email path. To send real email, either request that your provider unblock outbound port 25 on this instance and self-host a mail delivery service such as Postal, pointing `SMTP_HOST`, `SMTP_PORT`, `SMTP_USERNAME`, and `SMTP_PASSWORD` at it, or route outbound mail through an authenticated relay on port 587 or 465. Many cloud providers block outbound port 25 by default on new instances, so check with your provider before choosing a self-hosted mail path. Save and close the file. **3. Validate the syntax of the file:** $ docker compose config **4. Start the services in detached mode:** $ docker compose up -d **5. Verify that the containers are running and healthy:** $ docker compose ps All six containers should show a status of `Up`, with `mailpit`, `typebot-postgres`, and `typebot-redis` also showing `(healthy)`. **6. View the logs for the Builder service to ensure it connected successfully to the database and Redis:** $ docker compose logs typebot-builder **7. View the logs for the Viewer service to ensure it connected successfully to the database and Redis:** $ docker compose logs typebot-viewer ## Access and Configure Typebot Typebot requires email-based verification instead of a password for the first sign-in, which this deployment routes through Mailpit. This section confirms the administrator account, verifies that both the Builder and Viewer domains are reachable, and closes public registration. 1. Open your web browser and navigate to the Builder domain using HTTPS. https://builder.example.com Replace `builder.example.com` with the actual domain you set in the `.env` file for the Builder. 1. Sign in with the email address defined in the `ADMIN_EMAIL` variable. A six-digit verification code is sent to your Mailpit email server. 1. Because Mailpit is bound to `127.0.0.1` and not exposed publicly, access its web interface by setting up an SSH local port forwarding tunnel from your local terminal. $ ssh -N -L 8025:localhost:8025 USERNAME@YOUR_SERVER_IP Replace `USERNAME` with your server's username and `YOUR_SERVER_IP` with your server's IP. If your server uses key-based SSH authentication, add `-i /path/to/your-private-key` before `-N`. The `-N` flag tells SSH to only forward the port instead of opening a remote shell. 1. Open your local web browser and navigate to the Mailpit inbox at `http://localhost:8025`. 2. Open the Mailpit inbox and copy the verification code sent by Typebot. 1. Return to the Builder tab and enter the code to complete sign-in. 2. Return to the terminal running the SSH tunnel and press Ctrl+C to close it, since Mailpit access is no longer needed until the next sign-in. 3. Open the Viewer domain in a new tab. https://viewer.example.com Replace `viewer.example.com` with the domain you configured in the `.env` file. 1. Click the dashboard link on the Viewer page to verify that it opens the Builder interface. 1. Open your `.env` file to disable public registrations now that your admin account is created. $ nano .env 2. Update the signup configuration. DISABLE_SIGNUP=true 3. Save and close the file, then apply the changes to the Builder container. $ docker compose up -d --force-recreate typebot-builder > This prevents unauthorized users from registering new accounts on your public Builder instance. ## Create and Embed a Typebot Typebot publishes each bot as a hosted page on the Viewer domain and provides a JavaScript snippet that embeds that page into any website. Publishing a bot makes it reachable at that public link before you add it to a page. 1. In the Builder tab still open from the previous section, click **Create a typebot**. 2. Select **Start from scratch** to create a new bot manually. 1. From the top left corner, change the typebot name to your preferred title, for example, **My first bot**. 2. In the visual editor, drag a **Text** bubble block onto the canvas and enter a welcome message, for example, "Hello! How can I help you today?" 3. Drag a connection line from the **Start** block's output dot to the **Text** bubble block so the flow begins there. 4. Drag an Input block, for example **Text** , and connect it to the previous block. 1. Click **Publish** in the top-right corner. 2. Under **Embed your typebot** , click **Iframe**. 3. Copy the `<iframe>` snippet shown in the dialog. 4. Open the main HTML file of your sample website or any page where you want to add the bot. 5. Paste the snippet just before the closing `</body>` tag. <iframe title="Typebot" src="https://viewer.example.com/your-bot-id" style="border: none; width: 100%; height: 600px" ></iframe> Replace `viewer.example.com/your-bot-id` with the link shown in the Iframe dialog. 6. Save the file and open your website in a browser to test the bot. 7. Return to the Typebot Builder, open the **Results** tab, and verify that responses are being captured. ## Test a Bot Typebot's built-in templates route respondents through a Choice input block, so each button ends its own path through the flow instead of all leading to the same message. The Results tab records which option a respondent picked as its own column, alongside any text or email fields the flow collects. 1. Click **Create a typebot**. 2. Select **Start from template**. 3. Choose the **Customer Support** template from the left pane, then click **Use this template**. 4. Click **Publish**. 5. Open the link shown under **Your typebot links**. 6. Click one of the response options, for example **I have a feature request**. Verify that the bot responds with a follow-up message and a link, then click **Restart** to return to the beginning. 7. Return to the Typebot Builder, open the **Results** tab, and verify that the option you clicked appears under the **Menu** column. ## Next Steps * Connect a real SMTP provider so sign-in codes and notifications reach real inboxes * Explore Typebot's integrations, such as Google Sheets, webhooks, and Zapier * Build a multi-step lead qualification or support triage flow using Choice and Condition blocks * Set up scheduled backups of the PostgreSQL volume before handling production traffic For the full guide with additional tips, visit the original article on **Vultr Docs**.

BookStack is an open-source documentation platform for creating, organizing, and managing knowledge bases. It provides a web interface for structuring documentation into Shelves, Books, Chapters, and Pages, making it easy to organize technical documentation, internal wikis, project documentation, and team knowledge. This guide deploys BookStack on a Linux server using Docker Compose with MariaDB for data storage and Traefik as the reverse proxy for TLS termination, then walks through creating Shelves, Books, Chapters, and Pages through the web interface. By the end, you'll have a working BookStack instance with a sample documentation hierarchy served securely over HTTPS. ## Prerequisites Before you begin, you need to: * Have access to a Linux-based server (with at least 4 CPU cores and 8 GB of RAM) as a non-root user with sudo privileges. * Install Docker and Docker Compose. * Create a DNS A record pointing to your server's IP address (for example, `book.example.com`). ## Set Up the Directory Structure, Configuration, and Environment Variables BookStack requires a configuration file to define environment variables, database connections, and application settings. The setup includes persistent storage for the MariaDB database, uploaded files, and application configuration to ensure data is retained across server restarts. **1. Create the project directory:** $ mkdir ~/bookstack **2. Navigate to the project directory:** $ cd ~/bookstack **3. Generate a secret key for the BookStack application:** $ echo "base64:$(openssl rand -base64 32)" Save the output for use in the environment file. **4. Create an environment file:** $ nano .env **5. Add the following configuration:** DOMAIN=book.example.com LETSENCRYPT_EMAIL=admin@example.com # BookStack Settings APP_URL=https://book.example.com APP_KEY=YOUR_GENERATED_APP_KEY # Database Settings DB_DATABASE=bookstack DB_USERNAME=bookstack DB_PASSWORD=STRONG_DATABASE_PASSWORD_1 DB_ROOT_PASSWORD=STRONG_DATABASE_PASSWORD_2 # Time Zone TZ=UTC Replace: * `book.example.com` with your domain name. * `admin@example.com` with your email address. * `YOUR_GENERATED_APP_KEY` with the output from the earlier step. * `STRONG_DATABASE_PASSWORD_1` and `STRONG_DATABASE_PASSWORD_2` with two different secure passwords. Save and close the file. ## Deploy with Docker Compose The deployment stack uses Traefik as the reverse proxy for TLS termination and deploys BookStack and MariaDB containers with mounted application and database volumes. This configuration is based on the official BookStack Docker Compose configuration. **1. Create the Docker Compose manifest file:** $ nano docker-compose.yaml **2. Add the following configuration:** services: traefik: image: traefik:v3.7.11 container_name: traefik command: - "--providers.docker=true" - "--providers.docker.exposedbydefault=false" - "--entrypoints.web.address=:80" - "--entrypoints.websecure.address=:443" - "--entrypoints.web.http.redirections.entryPoint.to=websecure" - "--entrypoints.web.http.redirections.entryPoint.scheme=https" - "--certificatesresolvers.myresolver.acme.tlschallenge=true" - "--certificatesresolvers.myresolver.acme.email=${LETSENCRYPT_EMAIL}" - "--certificatesresolvers.myresolver.acme.storage=/letsencrypt/acme.json" ports: - "80:80" - "443:443" volumes: - /var/run/docker.sock:/var/run/docker.sock:ro - ./letsencrypt:/letsencrypt restart: unless-stopped mariadb: image: lscr.io/linuxserver/mariadb:11.8.8 container_name: bookstack_mariadb env_file: - .env environment: - PUID=1000 - PGID=1000 - TZ=${TZ} - MYSQL_ROOT_PASSWORD=${DB_ROOT_PASSWORD} - MYSQL_DATABASE=${DB_DATABASE} - MYSQL_USER=${DB_USERNAME} - MYSQL_PASSWORD=${DB_PASSWORD} volumes: - ./bookstack_data/mariadb_data:/config restart: unless-stopped bookstack: image: lscr.io/linuxserver/bookstack:version-v26.05.4 container_name: bookstack depends_on: - mariadb env_file: - .env environment: - PUID=1000 - PGID=1000 - TZ=${TZ} - APP_URL=${APP_URL} - APP_KEY=${APP_KEY} - DB_HOST=mariadb - DB_PORT=3306 - DB_DATABASE=${DB_DATABASE} - DB_USERNAME=${DB_USERNAME} - DB_PASSWORD=${DB_PASSWORD} volumes: - ./bookstack_data/app_data:/config labels: - "traefik.enable=true" - "traefik.http.routers.bookstack.rule=Host(`${DOMAIN}`)" - "traefik.http.routers.bookstack.entrypoints=websecure" - "traefik.http.routers.bookstack.tls.certresolver=myresolver" - "traefik.http.services.bookstack.loadbalancer.server.port=80" restart: unless-stopped Save and close the file. In the above manifest: * `traefik`: Serves as the reverse proxy and TLS termination point, using the official Traefik image. It exposes ports `80` and `443` for HTTP and HTTPS traffic, stores certificates in the `./letsencrypt` directory, and automatically provisions them through Let's Encrypt. * `mariadb`: Stores the BookStack database, including users, Shelves, Books, Chapters, Pages, and application data, using the LinuxServer.io MariaDB image. The database name, username, password, and root password come from the `.env` file, and the data persists in the `./bookstack_data/mariadb_data` directory. * `bookstack`: Runs the BookStack web application, using the LinuxServer.io BookStack image, and starts only after the `mariadb` service is available. The application URL, application key, database connection settings, and time zone come from the `.env` file, the application configuration and uploaded files persist in the `./bookstack_data/app_data` directory, and the Traefik labels route HTTPS requests for your domain to this container. All three services use `restart: unless-stopped`, so they restart automatically if they fail or the server reboots. **3. Start all services in detached mode:** $ docker compose up -d **4. Verify that the services are running:** $ docker compose ps The output displays all the containers in the `Up` state. **5. View the service logs to confirm all components started successfully:** $ docker compose logs ## Access and Configure BookStack BookStack provides a web interface for organizing and managing documentation using shelves, books, and pages. The dashboard provides a central place to manage your documentation and workspace. 1. Open your web browser and navigate to BookStack at `https://book.example.com`, replacing `book.example.com` with your configured domain. 1. On the screen, enter **Email** as `admin@admin.com` and **Password** as `password` to create the admin account. 2. Click **Log In** to access the BookStack dashboard. 1. To change the login password, click the **Admin** menu in the top-right navigation and select **My Account**. Then, under the **My Account** menu on the left, select **Access & Security**. From here, you can change your password and configure Multi-Factor Authentication (MFA). ## Build and Organize Your Documentation in BookStack BookStack organizes documentation into a hierarchy that makes related content easy to manage and navigate. This workflow creates a Shelf, builds a Book and Chapter within it, and adds a Page containing sample documentation to validate the setup and demonstrate the platform's core features. ### Create a Shelf A Shelf serves as the top-level container for organizing related Books within a documentation collection. 1. Click **Shelves** in the top navigation menu. 2. Click **Create one now** or **New Shelf** under the **Actions** panel. 3. Enter a shelf name, such as `Team Documentation`, and an optional description. 4. Click **Save Shelf**. ### Create a Book within the Shelf A Book groups related Chapters and Pages together within a Shelf. 1. Open the `Team Documentation` shelf you created in the previous step. 2. Click **Create New Book**. 3. Enter a book name, such as `Employee Onboarding`, and an optional description. 4. Click **Save Book**. ### Create a Chapter within the Book Chapters organize related Pages into logical sections within a Book. 1. Open the `Employee Onboarding` book you created in the previous step. 2. Click **Add a chapter**. 3. Enter a chapter name, such as `Getting Started`, and an optional description. 4. Click **Save Chapter**. ### Create and Edit a Page within the Chapter Pages are where you create, edit, and organize documentation using the built-in rich text editor. 1. Open the `Getting Started` chapter you created in the previous step. 2. Click **Create a new page**. 3. Enter a page title such as `Development Environment Setup`. 4. Add a brief introduction, followed by a heading titled `Prerequisites`. 5. Add a bulleted list describing the required software and tools. 6. Click **Save Page**. 1. Reopen the `Development Environment Setup` page, click **Edit** under the **Actions** panel, and add another heading named `Next Steps`, then click **Save Page** again. ## Next Steps * Invite additional users and configure role-based permissions for each Shelf or Book * Enable a search index and explore BookStack's built-in page revision history * Configure an external authentication provider such as LDAP or SAML for team sign-in * Set up scheduled backups of the MariaDB database and the uploaded file storage For the full guide with additional tips, visit the original article on **Vultr Docs**.

Uptime Kuma is a self-hosted monitoring tool that tracks the availability of websites, APIs, TCP ports, DNS records, and other services. It provides a clean dashboard to display uptime metrics and trigger alerts through 90+ notification services, including email, Slack, and Telegram, when a service goes down or recovers. This guide deploys Uptime Kuma on a Linux server using Docker Compose behind a Traefik reverse proxy. By the end, you'll have a working Uptime Kuma instance with an active monitor, a notification channel, and a public status page. ## Prerequisites Before you begin, you need to: * Have access to a Linux-based server as a non-root user with sudo privileges. * Install Docker and Docker Compose. * Configure a domain A record, such as `kuma.example.com`, pointing to your server's public IP address. * Add your user to the `docker` group to run Docker commands without `sudo`, then start a new shell session to apply the change. ## Set Up the Directory Structure and Environment Variables The project directory holds the Docker Compose file, the persistent data directory, and the environment variables shared between the Traefik and Uptime Kuma containers. **1. Create the project directory:** $ mkdir ~/uptime-kuma **2. Enter the project directory:** $ cd ~/uptime-kuma **3. Create the persistent data directory for Uptime Kuma:** $ mkdir -p data **4. Create the environment variable file:** $ nano .env **5. Add the following variables to the file:** DOMAIN=kuma.example.com LETSENCRYPT_EMAIL=admin@example.com Replace the following placeholders: * `kuma.example.com`: Your registered domain name pointing to the server's IP address. * `admin@example.com`: Your email address for Let's Encrypt certificate notifications. Save and close the file. ## Deploy with Docker Compose Traefik and Uptime Kuma run as separate containers on a shared Docker network. Traefik terminates TLS on the configured domain and forwards requests to Uptime Kuma's internal port, keeping Uptime Kuma off the public internet entirely. **1. Create the Docker Compose file:** $ nano docker-compose.yaml **2. Add the following configuration:** services: traefik: image: traefik:v3.7.11 container_name: traefik restart: unless-stopped command: - "--providers.docker=true" - "--providers.docker.exposedbydefault=false" - "--entrypoints.web.address=:80" - "--entrypoints.websecure.address=:443" - "--entrypoints.web.http.redirections.entrypoint.to=websecure" - "--entrypoints.web.http.redirections.entrypoint.scheme=https" - "--certificatesresolvers.le.acme.httpchallenge=true" - "--certificatesresolvers.le.acme.httpchallenge.entrypoint=web" - "--certificatesresolvers.le.acme.email=${LETSENCRYPT_EMAIL}" - "--certificatesresolvers.le.acme.storage=/letsencrypt/acme.json" ports: - "80:80" - "443:443" volumes: - /var/run/docker.sock:/var/run/docker.sock:ro - ./letsencrypt:/letsencrypt networks: - kuma-net uptime-kuma: image: louislam/uptime-kuma:2.5.3 container_name: uptime-kuma restart: unless-stopped volumes: - ./data:/app/data networks: - kuma-net labels: - "traefik.enable=true" - "traefik.http.routers.kuma.rule=Host(`${DOMAIN}`)" - "traefik.http.routers.kuma.entrypoints=websecure" - "traefik.http.routers.kuma.tls=true" - "traefik.http.routers.kuma.tls.certresolver=le" - "traefik.http.services.kuma.loadbalancer.server.port=3001" networks: kuma-net: driver: bridge Save and close the file. In the above configuration: * `traefik`: The reverse proxy that listens on ports `80` and `443`, redirects all HTTP traffic to HTTPS, and automatically provisions TLS certificates from Let's Encrypt using the HTTP challenge method. * `uptime-kuma`: The monitoring service that stores data in the `./data` directory. The Traefik labels configure domain routing, enable HTTPS, and forward traffic to the Uptime Kuma application on port `3001`. * `kuma-net`: A shared bridge network that allows Traefik and Uptime Kuma to communicate internally without exposing internal ports to the host. **3. Start all services in detached mode:** $ docker compose up -d **4. Verify that all containers are running:** $ docker compose ps The output displays two running containers: Traefik and Uptime Kuma. ## Configure Uptime Kuma Uptime Kuma does not report any status information until you create an administrator account and configure at least one monitor. 1. Open a web browser and navigate to the domain configured in the `.env` file. https://kuma.example.com 1. On the database setup page, select **SQLite** , then click **Next**. SQLite requires no extra configuration and works with the single-container deployment in this guide. The **MariaDB/MySQL** option connects to a separate database server that this deployment does not provision. 2. The account creation page appears. Enter a username, enter a strong password in both the **Password** and **Repeat Password** fields, then click **Create**. 3. After you create the account, the Uptime Kuma dashboard opens. Click **+ Add New Monitor**. 1. Configure the monitor settings: * **Monitor Type** : Select the type of service to monitor. Choose **HTTP(s)** for websites and APIs, **TCP Port** for port-based services, or **DNS** for domain records. * **Friendly Name** : Enter a descriptive name for the monitor (for example, `My Website`). * **URL** : Enter the full URL of the service to monitor (for example, `https://example.com`). * **Heartbeat Interval** : Set the polling frequency in seconds. The default is `60`. 1. Click **Save** to activate the monitor. The dashboard adds the monitor with an **Unknown** status. The status updates to **Up** or **Down** after the first heartbeat check runs within 60 seconds. ### Configure Alert Notifications Uptime Kuma does not send alerts by default. You must configure a notification channel and assign it to individual monitors before it triggers on a status change. 1. Click the profile avatar in the top-right corner and select **Settings**. 2. Navigate to the **Notifications** tab and click **Set Up Notification**. 3. Select a notification type from the dropdown. Supported channels include email (SMTP), Slack, Telegram, Discord, and PagerDuty, among others. 4. Enter the required credentials or webhook URL of the selected notification channel. 5. Click **Test** to send a test notification and verify the configuration is working. 6. Click **Save** to confirm the notification setup. 7. Open the settings for each monitor that should use this notification channel, select the notification from the **Notifications** list, and click **Save**. ## Create a Status Page A status page groups one or more monitors into a public view, separate from the administrator dashboard, so you can share it with users or team members without granting them access to the full Uptime Kuma interface. 1. Click **Status Pages** in the top navigation bar. 2. Click **New Status Page**. 3. Enter a **Name** for the status page (for example, `Service Status`), then enter a **Slug** using only lowercase letters, numbers, and hyphens (for example, `status` creates the URL `https://kuma.example.com/status/status`). Click **Next**. 4. The status page editor opens. The **Title** field is pre-filled with the name entered in the previous step. Add a **Description** if needed, then configure the remaining display settings as needed. 5. Click **Add Group** to create a section, then use the **Add a monitor** dropdown to select a monitor and add it to the group. 6. Click **Save** to publish the status page. 7. Open the status page URL in a browser to verify it loads and displays the monitor statuses. https://kuma.example.com/status/status Replace the path with the slug configured in step 3. ## Next Steps * Add more monitors for your other websites, APIs, and internal services * Configure additional notification channels so different teams get alerted through their preferred tool * Build separate status pages for internal and public audiences * Explore Uptime Kuma's tag and group features to organize monitors at scale For the full guide with additional tips, visit the original article on **Vultr Docs**.

So far, everything on your server is publicly reachable behind Traefik. But some things should run...

Multiple vulnerabilities were discovered in Traefik on July 9, 2026, as reported by CERT-FR. These flaws enable attackers to bypass security policies, though specific technical details such as CVE identifiers or affected versions were not disclosed in the notice. The vulnerabilities were identified without mentioning the discoverer or the exact attack vectors involved. No additional impacts, such as remote code execution or data exfiltration, were explicitly stated beyond the security policy bypass. The advisory was published under reference CERTFR-2026-AVI-0851.

Hetzner CX33 sunucumda Docker ve Portainer üzerinde yirmiye yakın servis koşturuyorum. n8n, Beszel, Grafana ve kendi yazdığım küçük paneller derken bir süre sonra iş çığırından çıktı. Her servise ayrı hesap açmak, her birinde iki adımlı doğrulamayı (MFA) tek tek kurmak ve şifreleri akılda tutmak tam bir eziyete dönüştü. İşin kötüsü, kullandığım bazı dahili araçlarda kullanıcı girişi özelliği bile yoktu; dış ağa açmak istesem doğrudan güvenlik riski yaratıyordu. İlk önce Keycloak düşündüm ama tek başına 2 GB RAM isteyen devasa bir Java canavarı. Authelia tarafı çok daha hafif olsa da yetenekleri daha çok proxy authentication ile sınırlı; modern uygulamalar için OIDC tarafı biraz zayıf kalıyor. Ortada hem modern OIDC/OAuth2 desteği veren hem de Nginx ya da Traefik önünde Forward Auth yapabilen en mantıklı açık kaynak seçenek olarak Authentik kaldı. Kurulumu yapıp tüm servisleri arkasına topladım. Sistem şu an tıkır tıkır çalışıyor. Ancak resmi dokümantasyonda yazmayan ya da arayüzde saç baş yolduran birkaç kritik ayrıntı var. Kurulum adımlarını, gerçek bellek tüketimini ve takıldığım pürüzleri doğrudan kendi notlarımdan aktarıyorum. ## Kaynak Tüketimi: Küçük Sunucusu Olanlar Dikkat Önce can alıcı noktadan başlayayım: Authentik öyle 'hafif' bir araç değil. Mimarisi dört ana parçadan oluşuyor: Authentik Server, Worker, PostgreSQL veritabanı ve Redis önbelleği. Konteynerleri ayağa kaldırdığınız an, henüz tek bir kullanıcı bile giriş yapmamışken boşta yaklaşık 1.2 GB ile 1.5 GB arasında RAM tüketiyor. Eğer 2 GB RAM'e sahip küçük bir VPS kullanıyorsanız, yanına başka bir servis koyduğunuz an Linux'un OOM Killer mekanizması devreye girip PostgreSQL'i anında öldürebilir. Bu yüzden sunucunuzda en az 2 GB veya 4 GB swap alanı açık değilse bu maceraya hiç girmeyin. Benim Hetzner CX33 makinede 8 GB RAM olduğu için sorun yaşamadım ama kenara mutlaka not edin. ## Docker Compose ile Kurulum Kurulum için resmi `compose.yml` dosyasını indirmek en temiz yol. Boş bir dizin oluşturup dosyayı çekiyoruz: mkdir -p ~/authentik && cd ~/authentik wget https://docs.goauthentik.io/compose.yml Authentik'in çalışması için iki adet rastgele gizli anahtara ihtiyacımız var. Biri PostgreSQL parolası, diğeri oturumları imzalamak için kullanılan anahtar. Terminalden şu iki satırı çalıştırarak doğrudan `.env` dosyasına yazdırabilirsiniz: echo "PG_PASS=$(openssl rand -base64 36 | tr -d '\n')" >> .env echo "AUTHENTIK_SECRET_KEY=$(openssl rand -base64 60 | tr -d '\n')" >> .env Burada ufak bir pürüz var: PostgreSQL 99 karakterden uzun parolalarda hata verebiliyor. Bu yüzden base64 çıktısını 36 karakterde tuttuk. Varsayılan ayarlarda Authentik HTTP için 9000, HTTPS için 9443 portunu dinler. Önünde Traefik veya CloudPanel gibi bir reverse proxy varsa portları değiştirmeden doğrudan 9000 portuna yönlendirme yapabilirsiniz. Konteynerleri başlatalım: docker compose pull docker compose up -d ## İlk Kurulum Tuzağı: akadmin Şifresi Konteynerler açıldığında tarayıcıdan doğrudan ana sayfaya giderseniz karşınıza boş bir giriş ekranı gelir. Elinizde henüz hiçbir kullanıcı adı ve şifre olmadığı için öylece kalırsınız. İlk kurulum için özel bir adrese gitmeniz gerekiyor: http://sunucu-ip-adresi:9000/if/flow/initial-setup/ Bu sayfaya girdiğinizde Authentik sizden varsayılan süper yönetici olan `akadmin` hesabı için bir şifre belirlemenizi ister. Şifreyi kaydedip panele giriş yapabilirsiniz. ## Arayüzdeki Labirent: Provider, Application ve Flow Mantığı Authentik yönetim paneline ilk girdiğinizde menüler arasında kaybolmanız işten bile değil. Akışı kafada netleştirmek için zinciri şöyle kurmak gerekiyor: * **Provider (Sağlayıcı):** Arkadaki servisle hangi dilden konuşacağınızı belirler. Örneğin Portainer için bir OAuth2/OIDC sağlayıcısı açarsınız. * **Application (Uygulama):** Kullanıcının gördüğü vitrindir. Uygulamaya bir isim verir, simgesini seçer ve az önce oluşturduğunuz Provider'ı buna bağlarsınız. * **Flows (Akışlar):** İşin en can alıcı kısmı burası. Giriş, kayıt, şifre sıfırlama gibi her işlem birer akıştan ibaret. Kullanıcı adı sorma, şifre denetleme ve iki adımlı doğrulama (MFA) aşamaları arka arkaya dizilir. Buradaki tek tehlike: Varsayılan akışlardan bir Stage (aşama) silerseniz kendinizi panelin dışına kilitleyebilirsiniz. Bu yüzden akışları kurcalamadan önce kopyasını alıp üzerinde deneme yapmak en mantıklısı. ## Portainer'ı OIDC ile Authentik'e Bağlamak Kendi sunucumda ilk bağladığım servis Portainer oldu. Yapılandırma adımları şu şekilde: 1. Authentik panelinde `Applications -> Providers` sekmesinden yeni bir `OAuth2/OpenID Provider` oluşturdum. Redirect URI olarak Portainer adresimi yazdım: `https://portainer.alanadiniz.com/` 2. Sistem bana bir `Client ID` ve `Client Secret` verdi. Ardından `Applications` altından yeni bir uygulama açıp bu Provider ile eşleştirdim. 3. Portainer tarafında `Settings -> Authentication` bölümüne geçip OAuth'u seçtim. Aldığım ID ve Secret bilgilerini yapıştırdım. 4. OpenID Configuration URL alanına Authentik'in keşif adresini girdim: `https://auth.alanadiniz.com/application/o/portainer/.well-known/openid-configuration` Kaydettiğim an Portainer giriş ekranına 'Login with OAuth' seçeneği geldi. Artık Portainer üzerinde ayrı bir şifre tutmuyorum; Authentik üzerinden Passkey (Touch ID) ile tek dokunuşla panele giriyorum. ## Giriş Ekranı Olmayan Araçlar İçin: Traefik ile Forward Auth Beni Authentik kurmaya asıl iten ihtiyaç, içinde kullanıcı girişi bulunmayan dahili panellerdi. Örneğin basit bir durum izleme ekranı veya arka planda çalışan bir kuyruk yöneticisi. Authentik'in içindeki `Proxy Outpost` bileşeni burada devreye giriyor. Authentik üzerinde Forward Auth modunda bir Proxy Provider tanımlıyorsunuz. Traefik tarafında bir middleware kuralı yazarak trafiği önce bu Outpost'a yönlendiriyorsunuz. Kullanıcı adrese gitmek istediğinde Traefik önce Authentik'e soruyor. Oturum açıksa istek servise geçiyor, oturum yoksa doğrudan Authentik giriş ekranı açılıyor. Servisin kaynak kodunda tek bir satır kullanıcı yönetimi olmasa bile önünde iki adımlı doğrulamalı tam bir güvenlik kalkanı oluşuyor. ## Yaşayarak Öğrendiğim İki Önemli Detay Kurulum yaparken tökezlediğim ve zaman kaybettiren iki konuyu buraya özellikle bırakıyorum: * **UTC Zamanı ve Login Loop Hatası:** Authentik konteynerlerine sunucunun yerel saat dosyasını (`/etc/localtime`) kesinlikle bağlamayın. Authentik içeride tamamen UTC ile çalışır. Sunucuyla konteyner arasında birkaç saniyelik bile zaman kayması olursa OIDC token'ları geçersiz sayılır ve oturum açmaya çalıştığınızda sürekli giriş ekranına geri fırlatılırsınız. * **Docker Soketi ve Outpost Güvenliği:** Authentik worker konteyneri varsayılan yapılandırmada `/var/run/docker.sock` dosyasını ister. Amacı Outpost konteynerlerini otomatik yönetmektir. Eğer Docker soketini bir konteynere teslim etmek istemiyorsanız bu satırı kaldırabilirsiniz; bu durumda Outpost'u bağımsız bir compose dosyasıyla manuel çalıştırmanız gerekir. ## Son Söz Authentik, 1.5 GB civarındaki RAM ayak izi ve arayüzündeki akış karmaşasını göze alırsanız, Docker altyapınız için kurabileceğiniz en derli toplu kimlik sağlayıcı. Özellikle Portainer, Grafana gibi OIDC destekleyen araçlarla, giriş ekranı olmayan dahili servisleri tek bir merkezde toplamak istiyorsanız harcadığınız zamana kesinlikle değiyor.

See how Traefik Hub enforces one refund across token claims, gateway policy, and a policy engine.