<?xml version="1.0" encoding="UTF-8"?>
<rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom" xmlns:dc="http://purl.org/dc/elements/1.1/">
  <channel>
    <title>DEV Community: konsongong</title>
    <description>The latest articles on DEV Community by konsongong (@gongkang).</description>
    <link>https://dev.to/gongkang</link>
    <image>
      <url>https://media2.dev.to/dynamic/image/width=90,height=90,fit=cover,gravity=auto,format=auto/https:%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Fuser%2Fprofile_image%2F4247586%2Fbf09e217-da19-453e-b553-28767b36c8ec.png</url>
      <title>DEV Community: konsongong</title>
      <link>https://dev.to/gongkang</link>
    </image>
    <atom:link rel="self" type="application/rss+xml" href="https://dev.to/feed/gongkang"/>
    <language>en</language>
    <item>
      <title>Self-Host Vaultwarden with Docker Compose: Lightweight Bitwarden Server</title>
      <dc:creator>konsongong</dc:creator>
      <pubDate>Mon, 16 Nov 2026 12:29:00 +0000</pubDate>
      <link>https://dev.to/gongkang/self-host-vaultwarden-with-docker-compose-lightweight-bitwarden-server-17ab</link>
      <guid>https://dev.to/gongkang/self-host-vaultwarden-with-docker-compose-lightweight-bitwarden-server-17ab</guid>
      <description>&lt;blockquote&gt;
&lt;p&gt;This tutorial was written with AI assistance from the project's official documentation. Verification status is stated at the end of the article.&lt;/p&gt;
&lt;/blockquote&gt;

&lt;h2&gt;
  
  
  What Vaultwarden does and what it needs
&lt;/h2&gt;

&lt;p&gt;Vaultwarden is a Rust reimplementation of the Bitwarden client API. It speaks the same protocol as the official Bitwarden clients (browser extensions, mobile, desktop, CLI), so you point them at your own server instead of bitwarden.com. The upstream project targets self-hosters who don't want to run the resource-heavy official stack.&lt;/p&gt;

&lt;p&gt;Feature coverage is broad: personal vault, Send, attachments, website icons, organizations with collections and groups, event logs, admin password reset, TOTP/email/FIDO2/YubiKey/Duo 2FA, emergency access, and the Vaultwarden admin backend. The web vault is bundled inside the container image.&lt;/p&gt;

&lt;p&gt;The upstream project does not publish a minimum memory figure. In practice, idle memory is modest because the binary is Rust and the default database is SQLite. Memory grows with concurrent client syncs, attachment uploads, and icon-cache fetches. If you enable a MySQL or PostgreSQL backend, budget for that database process too.&lt;/p&gt;

&lt;p&gt;One hard requirement from the README: the web vault needs a secure context for the Web Crypto API. That means HTTPS. Plain HTTP on a public IP will not work for the browser vault.&lt;/p&gt;

&lt;h2&gt;
  
  
  Prerequisites, ports, and volume constraints
&lt;/h2&gt;

&lt;ul&gt;
&lt;li&gt;A Linux host with Docker Engine 24+ and the Compose plugin (&lt;code&gt;docker compose version&lt;/code&gt;).&lt;/li&gt;
&lt;li&gt;A DNS record pointing at the host, e.g. &lt;code&gt;vw.example.com&lt;/code&gt;. You need this before the reverse proxy step.&lt;/li&gt;
&lt;li&gt;Port 80 and 443 free for the reverse proxy. Vaultwarden itself listens on container port 80 (the image maps &lt;code&gt;ROCKET_PORT=8000&lt;/code&gt; internally but the container exposes 80).&lt;/li&gt;
&lt;li&gt;A persistent volume for &lt;code&gt;/data&lt;/code&gt;. This holds &lt;code&gt;db.sqlite3&lt;/code&gt;, &lt;code&gt;rsa_key&lt;/code&gt;, &lt;code&gt;attachments/&lt;/code&gt;, &lt;code&gt;sends/&lt;/code&gt;, &lt;code&gt;icon_cache/&lt;/code&gt;, and &lt;code&gt;tmp/&lt;/code&gt;. Lose it and you lose every vault.&lt;/li&gt;
&lt;li&gt;Outbound HTTPS if you keep &lt;code&gt;ICON_SERVICE=internal&lt;/code&gt; (default) so the server can fetch site icons. Set &lt;code&gt;DISABLE_ICON_DOWNLOAD=true&lt;/code&gt; if you want to block that.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;The official README example publishes &lt;code&gt;127.0.0.1:8000:80&lt;/code&gt;. We keep that binding so the app is reachable only from the host and the reverse proxy terminates TLS.&lt;/p&gt;

&lt;h2&gt;
  
  
  Production Docker Compose setup
&lt;/h2&gt;

&lt;p&gt;Create the project directory and the data volume, then write the compose file and &lt;code&gt;.env&lt;/code&gt;.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;mkdir -p /opt/vaultwarden &lt;span class="o"&gt;&amp;amp;&amp;amp;&lt;/span&gt; &lt;span class="nb"&gt;cd&lt;/span&gt; /opt/vaultwarden
mkdir -p vw-data
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Generate secrets. &lt;code&gt;ADMIN_TOKEN&lt;/code&gt; protects the &lt;code&gt;/admin&lt;/code&gt; panel; treat it like a root password. The &lt;code&gt;PUSH_INSTALLATION_KEY&lt;/code&gt; is only needed if you enable mobile push, but generating it now avoids a later restart.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;openssl rand -hex 32   &lt;span class="c"&gt;# ADMIN_TOKEN&lt;/span&gt;
openssl rand -hex 32   &lt;span class="c"&gt;# PUSH_INSTALLATION_KEY (optional)&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Write &lt;code&gt;.env&lt;/code&gt; (replace the placeholders with the values you just generated, and set &lt;code&gt;DOMAIN&lt;/code&gt; to your real HTTPS URL):&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;cat &lt;span class="o"&gt;&amp;lt;&amp;lt;&lt;/span&gt;&lt;span class="s1"&gt;'EOF'&lt;/span&gt; &lt;span class="o"&gt;&amp;gt;&lt;/span&gt; .env
&lt;span class="nv"&gt;DOMAIN&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;https://vw.example.com
&lt;span class="nv"&gt;ADMIN_TOKEN&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;REPLACE_WITH_OPENSSL_HEX
&lt;span class="nv"&gt;PUSH_INSTALLATION_KEY&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;REPLACE_WITH_OPENSSL_HEX
&lt;span class="nv"&gt;SIGNUPS_ALLOWED&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="kc"&gt;true&lt;/span&gt;
&lt;span class="nv"&gt;TZ&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;UTC
&lt;span class="nv"&gt;LOG_LEVEL&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;info
EOF
chmod 600 .env
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Write &lt;code&gt;compose.yml&lt;/code&gt;:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;cat &lt;span class="o"&gt;&amp;lt;&amp;lt;&lt;/span&gt;&lt;span class="s1"&gt;'EOF'&lt;/span&gt; &lt;span class="o"&gt;&amp;gt;&lt;/span&gt; compose.yml
services:
  vaultwarden:
    image: vaultwarden/server:latest
    container_name: vaultwarden
    restart: unless-stopped
    environment:
      DOMAIN: &lt;span class="nv"&gt;${DOMAIN}&lt;/span&gt;
      ADMIN_TOKEN: &lt;span class="nv"&gt;${ADMIN_TOKEN}&lt;/span&gt;
      PUSH_INSTALLATION_KEY: &lt;span class="nv"&gt;${PUSH_INSTALLATION_KEY}&lt;/span&gt;
      SIGNUPS_ALLOWED: &lt;span class="nv"&gt;${SIGNUPS_ALLOWED:-true}&lt;/span&gt;
      TZ: &lt;span class="nv"&gt;${TZ:-UTC}&lt;/span&gt;
      LOG_LEVEL: &lt;span class="nv"&gt;${LOG_LEVEL:-info}&lt;/span&gt;
      ENABLE_WEBSOCKET: &lt;span class="s2"&gt;"true"&lt;/span&gt;
      IP_HEADER: X-Real-IP
      IP_HEADER_TRUSTED_PROXIES: &lt;span class="kd"&gt;local&lt;/span&gt;
    volumes:
      - ./vw-data:/data
    ports:
      - 127.0.0.1:8000:80
EOF
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Start it:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;docker compose up -d
docker compose logs -f vaultwarden
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;You should see Rocket bind and a line about the database. The app is now listening on &lt;code&gt;127.0.0.1:8000&lt;/code&gt; only. To test without a domain, either SSH-tunnel (&lt;code&gt;ssh -L 8000:127.0.0.1:8000 user@host&lt;/code&gt;) and open &lt;code&gt;http://localhost:8000&lt;/code&gt;, or temporarily change the port mapping to &lt;code&gt;8000:80&lt;/code&gt; and accept that the web vault will refuse to run over plain HTTP.&lt;/p&gt;

&lt;h2&gt;
  
  
  Reverse proxy, HTTPS, and first-run hardening
&lt;/h2&gt;

&lt;p&gt;Vaultwarden's README is explicit: use a reverse proxy and enable HTTPS. The web vault will not function without a secure context. The proxy must also forward WebSocket upgrades because &lt;code&gt;ENABLE_WEBSOCKET=true&lt;/code&gt; is set above; the Bitwarden clients use the WebSocket for live sync notifications.&lt;/p&gt;

&lt;p&gt;Caddy example (&lt;code&gt;/etc/caddy/Caddyfile&lt;/code&gt;):&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight vcl"&gt;&lt;code&gt;vw.example.com &lt;span class="o"&gt;{&lt;/span&gt;
    encode zstd gzip
    reverse_proxy 127.0.0.1:8000
&lt;span class="o"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Caddy handles WebSocket upgrades automatically and provisions a Let's Encrypt certificate once DNS resolves. If you use Nginx instead, you need explicit upgrade headers:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight nginx"&gt;&lt;code&gt;&lt;span class="n"&gt;location&lt;/span&gt; &lt;span class="o"&gt;/&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="n"&gt;proxy_pass&lt;/span&gt; &lt;span class="n"&gt;http&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="c1"&gt;//127.0.0.1:8000;&lt;/span&gt;
    &lt;span class="n"&gt;proxy_set_header&lt;/span&gt; &lt;span class="nc"&gt;Host&lt;/span&gt; $&lt;span class="n"&gt;host&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
    &lt;span class="n"&gt;proxy_set_header&lt;/span&gt; &lt;span class="no"&gt;X&lt;/span&gt;&lt;span class="o"&gt;-&lt;/span&gt;&lt;span class="nc"&gt;Real&lt;/span&gt;&lt;span class="o"&gt;-&lt;/span&gt;&lt;span class="no"&gt;IP&lt;/span&gt; $&lt;span class="n"&gt;remote_addr&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
    &lt;span class="n"&gt;proxy_set_header&lt;/span&gt; &lt;span class="no"&gt;X&lt;/span&gt;&lt;span class="o"&gt;-&lt;/span&gt;&lt;span class="nc"&gt;Forwarded&lt;/span&gt;&lt;span class="o"&gt;-&lt;/span&gt;&lt;span class="nc"&gt;For&lt;/span&gt; $&lt;span class="n"&gt;proxy_add_x_forwarded_for&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
    &lt;span class="n"&gt;proxy_set_header&lt;/span&gt; &lt;span class="no"&gt;X&lt;/span&gt;&lt;span class="o"&gt;-&lt;/span&gt;&lt;span class="nc"&gt;Forwarded&lt;/span&gt;&lt;span class="o"&gt;-&lt;/span&gt;&lt;span class="nc"&gt;Proto&lt;/span&gt; $&lt;span class="n"&gt;scheme&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
    &lt;span class="n"&gt;proxy_http_version&lt;/span&gt; &lt;span class="mf"&gt;1.1&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
    &lt;span class="n"&gt;proxy_set_header&lt;/span&gt; &lt;span class="nc"&gt;Upgrade&lt;/span&gt; $&lt;span class="n"&gt;http_upgrade&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
    &lt;span class="n"&gt;proxy_set_header&lt;/span&gt; &lt;span class="nc"&gt;Connection&lt;/span&gt; &lt;span class="s2"&gt;"upgrade"&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
    &lt;span class="n"&gt;client_max_body_size&lt;/span&gt; &lt;span class="mi"&gt;525M&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The &lt;code&gt;client_max_body_size&lt;/code&gt; matters: attachments and Sends are uploaded through the proxy, and the default 1 MB Nginx limit will break them. Caddy has no such limit by default.&lt;/p&gt;

&lt;p&gt;&lt;code&gt;DOMAIN&lt;/code&gt; in &lt;code&gt;.env&lt;/code&gt; must match the public URL exactly, including scheme and any subpath. The Bitwarden clients read it from the server config and use it for WebSocket and API calls. A mismatch causes sync failures that look like network errors.&lt;/p&gt;

&lt;p&gt;First-run hardening, in order:&lt;/p&gt;

&lt;ol&gt;
&lt;li&gt;Open &lt;code&gt;https://vw.example.com&lt;/code&gt; and register your account. The first account is the one you'll use.&lt;/li&gt;
&lt;li&gt;Immediately set &lt;code&gt;SIGNUPS_ALLOWED=false&lt;/code&gt; in &lt;code&gt;.env&lt;/code&gt; and run &lt;code&gt;docker compose up -d&lt;/code&gt; to recreate the container. Otherwise anyone who finds the host can create an account.&lt;/li&gt;
&lt;li&gt;Log in to &lt;code&gt;https://vw.example.com/admin&lt;/code&gt; with the &lt;code&gt;ADMIN_TOKEN&lt;/code&gt; and confirm the panel loads. If it doesn't, the token in &lt;code&gt;.env&lt;/code&gt; doesn't match what the container read; check &lt;code&gt;docker compose config&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;Enable 2FA on your account from the web vault settings. Vaultwarden supports TOTP, email, FIDO2, YubiKey, and Duo.&lt;/li&gt;
&lt;li&gt;If you plan to invite others, configure SMTP (&lt;code&gt;SMTP_HOST&lt;/code&gt;, &lt;code&gt;SMTP_FROM&lt;/code&gt;, &lt;code&gt;SMTP_SECURITY&lt;/code&gt;, &lt;code&gt;SMTP_PORT&lt;/code&gt;, &lt;code&gt;SMTP_USERNAME&lt;/code&gt;, &lt;code&gt;SMTP_PASSWORD&lt;/code&gt;) so invitation and verification emails actually send. Without SMTP, invitations silently fail.&lt;/li&gt;
&lt;/ol&gt;

&lt;h2&gt;
  
  
  Updating, backups, and common pitfalls
&lt;/h2&gt;

&lt;p&gt;Update:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;&lt;span class="nb"&gt;cd&lt;/span&gt; /opt/vaultwarden
docker compose pull
docker compose up -d
docker compose logs --tail=50 vaultwarden
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Vaultwarden migrations run on startup. Read the release notes before jumping major versions; the project occasionally changes defaults.&lt;/p&gt;

&lt;p&gt;Backup. The only state that matters is the &lt;code&gt;vw-data&lt;/code&gt; directory (mounted at &lt;code&gt;/data&lt;/code&gt;). Stop the container for a consistent SQLite snapshot, or use SQLite's online backup if you can't afford downtime:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;&lt;span class="nb"&gt;cd&lt;/span&gt; /opt/vaultwarden
docker compose stop vaultwarden
tar czf vaultwarden-&lt;span class="nv"&gt;$(&lt;/span&gt;date +%F&lt;span class="o"&gt;)&lt;/span&gt;.tar.gz vw-data
docker compose start vaultwarden
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Store that tarball off-host. It contains &lt;code&gt;db.sqlite3&lt;/code&gt;, &lt;code&gt;rsa_key&lt;/code&gt; (used to sign auth tokens), attachments, and Sends. Restoring is the reverse: stop, replace &lt;code&gt;vw-data&lt;/code&gt;, start.&lt;/p&gt;

&lt;p&gt;Two pitfalls worth knowing:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;The web vault needs HTTPS, full stop.&lt;/strong&gt; The README calls this out because the Web Crypto API requires a secure context. If you test over plain HTTP, the vault UI will load but crypto operations fail. Don't debug the app; fix the TLS termination.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;&lt;code&gt;DOMAIN&lt;/code&gt; must be the public URL, not the internal one.&lt;/strong&gt; Setting &lt;code&gt;DOMAIN=http://localhost&lt;/code&gt; or &lt;code&gt;DOMAIN=http://127.0.0.1:8000&lt;/code&gt; while serving over HTTPS breaks client sync and WebSocket connections. The value is handed to clients as the server base URL.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;If you enable mobile push later, set &lt;code&gt;PUSH_ENABLED=true&lt;/code&gt; and keep &lt;code&gt;PUSH_INSTALLATION_ID&lt;/code&gt; and &lt;code&gt;PUSH_INSTALLATION_KEY&lt;/code&gt; stable across restarts; regenerating them invalidates registrations. For most self-hosters, leaving push off is fine and avoids sending metadata to Bitwarden's relay.&lt;/p&gt;




&lt;p&gt;&lt;strong&gt;Measured in our sandbox run:&lt;/strong&gt; total memory 7.1 MB (sum of per-container peaks over a 30s idle window after startup) across 1 container; largest container 7.1 MB; published port(s) 8000; HTTP probe returned 200. The run took 99.3s with the image already cached; a fresh server also has to download it. Required secret(s) ADMIN_TOKEN, DOMAIN, PUSH_INSTALLATION_KEY were generated for the test run, as the tutorial instructs.&lt;/p&gt;




&lt;p&gt;&lt;em&gt;Verification: we ran this docker-compose stack in a disposable Docker environment and recorded the measurements above. They describe that run, not a guarantee for your host.&lt;/em&gt;&lt;/p&gt;




&lt;p&gt;&lt;em&gt;Originally published with full interactive benchmark metrics and server sizing notes at &lt;a href="https://benchrun.pages.dev/vaultwarden-docker-compose-self-hosting/" rel="noopener noreferrer"&gt;https://benchrun.pages.dev/vaultwarden-docker-compose-self-hosting/&lt;/a&gt;.&lt;/em&gt;&lt;/p&gt;

</description>
      <category>vaultwarden</category>
      <category>bitwarden</category>
      <category>docker</category>
      <category>passwordmanager</category>
    </item>
    <item>
      <title>Self-Host Sure Personal Finance with Docker Compose</title>
      <dc:creator>konsongong</dc:creator>
      <pubDate>Mon, 16 Nov 2026 12:04:34 +0000</pubDate>
      <link>https://dev.to/gongkang/how-to-self-host-sure-on-a-vps-with-docker-2026-guide-5cjk</link>
      <guid>https://dev.to/gongkang/how-to-self-host-sure-on-a-vps-with-docker-2026-guide-5cjk</guid>
      <description>&lt;blockquote&gt;
&lt;p&gt;This tutorial was written with AI assistance from the project's official documentation. Verification status is stated at the end of the article.&lt;/p&gt;
&lt;/blockquote&gt;

&lt;h2&gt;
  
  
  What Sure does and what it needs
&lt;/h2&gt;

&lt;p&gt;Sure is a community-maintained fork of the abandoned Maybe Finance codebase. It's a full personal finance app: accounts, transactions, budgets, net worth tracking, investment holdings, AI-assisted categorization, and a chat assistant. You can reach it from a browser, the macOS desktop app, mobile clients, and API/LLM agents.&lt;/p&gt;

&lt;p&gt;The stack is a standard Rails deployment:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;web&lt;/strong&gt; — the Rails app served by Puma on port 3000 inside the container.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;worker&lt;/strong&gt; — Sidekiq, which runs scheduled jobs (market data sync, rule notifications, PDF import follow-ups) and sends email.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;db&lt;/strong&gt; — PostgreSQL 16, holding all financial data.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;redis&lt;/strong&gt; — Sidekiq's queue backend (database 1 by default).&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;app-storage&lt;/strong&gt; — a named volume mounted at &lt;code&gt;/rails/storage&lt;/code&gt; for Active Storage uploads (imported PDFs, attachments).&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;The upstream project does not publish a minimum RAM figure. Plan around workload: an idle instance with a few accounts is light, but PDF imports, market data syncs, and AI chat turns are the memory-heavy paths. If you enable OpenAI-backed features, budget for the outbound API calls too.&lt;/p&gt;

&lt;h2&gt;
  
  
  Prerequisites, ports, and volume constraints
&lt;/h2&gt;

&lt;ul&gt;
&lt;li&gt;Docker Engine and the Compose plugin on a Linux host.&lt;/li&gt;
&lt;li&gt;A domain name if you want HTTPS. The app itself speaks plain HTTP; TLS terminates at your reverse proxy.&lt;/li&gt;
&lt;li&gt;Port &lt;strong&gt;3000&lt;/strong&gt; is the app's internal port. In this guide we bind it to &lt;code&gt;127.0.0.1:3000&lt;/code&gt; so only the reverse proxy on the same host can reach it.&lt;/li&gt;
&lt;li&gt;Two named volumes matter: &lt;code&gt;postgres-data&lt;/code&gt; (the database) and &lt;code&gt;app-storage&lt;/code&gt; (uploads). Back both up.&lt;/li&gt;
&lt;li&gt;
&lt;code&gt;SECRET_KEY_BASE&lt;/code&gt; is mandatory and has no default. It also seeds Active Record encryption keys when &lt;code&gt;ACTIVE_RECORD_ENCRYPTION_*&lt;/code&gt; are unset, so a guessable value lets anyone forge session cookies and derive your encryption keys. Generate it with &lt;code&gt;openssl rand -hex 64&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;If you're upgrading an existing install, &lt;strong&gt;keep the existing &lt;code&gt;SECRET_KEY_BASE&lt;/code&gt;&lt;/strong&gt;. Generating a new one makes already-encrypted data unreadable.&lt;/li&gt;
&lt;/ul&gt;

&lt;h2&gt;
  
  
  Production Docker Compose setup
&lt;/h2&gt;

&lt;p&gt;Create the project directory and write the compose file. This mirrors the official &lt;code&gt;compose.example.yml&lt;/code&gt; but binds the web port to localhost and wires the production variables through &lt;code&gt;.env&lt;/code&gt;.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;mkdir -p ~/docker-apps/sure
&lt;span class="nb"&gt;cd&lt;/span&gt; ~/docker-apps/sure

cat &lt;span class="o"&gt;&amp;lt;&amp;lt;&lt;/span&gt;&lt;span class="s1"&gt;'EOF'&lt;/span&gt; &lt;span class="o"&gt;&amp;gt;&lt;/span&gt; compose.yml
x-db-env: &lt;span class="o"&gt;&amp;amp;&lt;/span&gt;db_env
  POSTGRES_USER: &lt;span class="nv"&gt;${POSTGRES_USER:-sure_user}&lt;/span&gt;
  POSTGRES_PASSWORD: &lt;span class="nv"&gt;${POSTGRES_PASSWORD}&lt;/span&gt;
  POSTGRES_DB: &lt;span class="nv"&gt;${POSTGRES_DB:-sure_production}&lt;/span&gt;

x-rails-env: &lt;span class="o"&gt;&amp;amp;&lt;/span&gt;rails_env
  &lt;span class="o"&gt;&amp;lt;&amp;lt;&lt;/span&gt;: *db_env
  SECRET_KEY_BASE: &lt;span class="nv"&gt;${SECRET_KEY_BASE}&lt;/span&gt;
  ACTIVE_RECORD_ENCRYPTION_PRIMARY_KEY: &lt;span class="nv"&gt;${ACTIVE_RECORD_ENCRYPTION_PRIMARY_KEY:-}&lt;/span&gt;
  ACTIVE_RECORD_ENCRYPTION_DETERMINISTIC_KEY: &lt;span class="nv"&gt;${ACTIVE_RECORD_ENCRYPTION_DETERMINISTIC_KEY:-}&lt;/span&gt;
  ACTIVE_RECORD_ENCRYPTION_KEY_DERIVATION_SALT: &lt;span class="nv"&gt;${ACTIVE_RECORD_ENCRYPTION_KEY_DERIVATION_SALT:-}&lt;/span&gt;
  SELF_HOSTED: &lt;span class="s2"&gt;"true"&lt;/span&gt;
  ONBOARDING_STATE: &lt;span class="nv"&gt;${ONBOARDING_STATE:-open}&lt;/span&gt;
  RAILS_FORCE_SSL: &lt;span class="s2"&gt;"false"&lt;/span&gt;
  RAILS_ASSUME_SSL: &lt;span class="s2"&gt;"true"&lt;/span&gt;
  APP_DOMAIN: &lt;span class="nv"&gt;${APP_DOMAIN}&lt;/span&gt;
  DB_HOST: db
  DB_PORT: 5432
  REDIS_URL: redis://redis:6379/1
  SIDEKIQ_CRON_GRACE_PERIOD_SECONDS: &lt;span class="nv"&gt;${SIDEKIQ_CRON_GRACE_PERIOD_SECONDS:-}&lt;/span&gt;
  OPENAI_ACCESS_TOKEN: &lt;span class="nv"&gt;${OPENAI_ACCESS_TOKEN:-}&lt;/span&gt;
  OPENAI_MODEL: &lt;span class="nv"&gt;${OPENAI_MODEL:-}&lt;/span&gt;
  OPENAI_URI_BASE: &lt;span class="nv"&gt;${OPENAI_URI_BASE:-}&lt;/span&gt;
  OPENAI_REQUEST_TIMEOUT: &lt;span class="nv"&gt;${OPENAI_REQUEST_TIMEOUT:-60}&lt;/span&gt;
  AI_RESPONSE_TIMEOUT: &lt;span class="nv"&gt;${AI_RESPONSE_TIMEOUT:-90}&lt;/span&gt;
  ASSISTANT_MAX_TOOL_CALL_ITERATIONS: &lt;span class="nv"&gt;${ASSISTANT_MAX_TOOL_CALL_ITERATIONS:-}&lt;/span&gt;
  SMTP_ADDRESS: &lt;span class="nv"&gt;${SMTP_ADDRESS:-}&lt;/span&gt;
  SMTP_PORT: &lt;span class="nv"&gt;${SMTP_PORT:-465}&lt;/span&gt;
  SMTP_USERNAME: &lt;span class="nv"&gt;${SMTP_USERNAME:-}&lt;/span&gt;
  SMTP_PASSWORD: &lt;span class="nv"&gt;${SMTP_PASSWORD:-}&lt;/span&gt;
  SMTP_TLS_ENABLED: &lt;span class="nv"&gt;${SMTP_TLS_ENABLED:-true}&lt;/span&gt;
  SMTP_TLS_SKIP_VERIFY: &lt;span class="nv"&gt;${SMTP_TLS_SKIP_VERIFY:-false}&lt;/span&gt;
  EMAIL_SENDER: &lt;span class="nv"&gt;${EMAIL_SENDER:-}&lt;/span&gt;
  EXCHANGE_RATE_PROVIDER: &lt;span class="nv"&gt;${EXCHANGE_RATE_PROVIDER:-yahoo_finance}&lt;/span&gt;
  SECURITIES_PROVIDER: &lt;span class="nv"&gt;${SECURITIES_PROVIDER:-yahoo_finance}&lt;/span&gt;

services:
  web:
    image: ghcr.io/we-promise/sure:&lt;span class="nv"&gt;${SURE_IMAGE_TAG:-stable}&lt;/span&gt;
    volumes:
      - app-storage:/rails/storage
    ports:
      - 127.0.0.1:&lt;span class="nv"&gt;${PORT:-3000}&lt;/span&gt;:3000
    restart: unless-stopped
    environment:
      &lt;span class="o"&gt;&amp;lt;&amp;lt;&lt;/span&gt;: *rails_env
    depends_on:
      db:
        condition: service_healthy
      redis:
        condition: service_healthy
    dns:
      - 8.8.8.8
      - 1.1.1.1
    networks:
      - sure_net

  worker:
    image: ghcr.io/we-promise/sure:&lt;span class="nv"&gt;${SURE_IMAGE_TAG:-stable}&lt;/span&gt;
    command: bundle &lt;span class="nb"&gt;exec&lt;/span&gt; sidekiq
    volumes:
      - app-storage:/rails/storage
    restart: unless-stopped
    depends_on:
      db:
        condition: service_healthy
      redis:
        condition: service_healthy
    dns:
      - 8.8.8.8
      - 1.1.1.1
    environment:
      &lt;span class="o"&gt;&amp;lt;&amp;lt;&lt;/span&gt;: *rails_env
    networks:
      - sure_net

  db:
    image: postgres:16
    restart: unless-stopped
    volumes:
      - postgres-data:/var/lib/postgresql/data
    environment:
      &lt;span class="o"&gt;&amp;lt;&amp;lt;&lt;/span&gt;: *db_env
    healthcheck:
      test: &lt;span class="o"&gt;[&lt;/span&gt;&lt;span class="s2"&gt;"CMD-SHELL"&lt;/span&gt;, &lt;span class="s2"&gt;"pg_isready -U $$POSTGRES_USER -d $$POSTGRES_DB"&lt;/span&gt;&lt;span class="o"&gt;]&lt;/span&gt;
      interval: 5s
      timeout: 5s
      retries: 5
    networks:
      - sure_net

  redis:
    image: redis:7-alpine
    restart: unless-stopped
    volumes:
      - redis-data:/data
    healthcheck:
      test: &lt;span class="o"&gt;[&lt;/span&gt;&lt;span class="s2"&gt;"CMD"&lt;/span&gt;, &lt;span class="s2"&gt;"redis-cli"&lt;/span&gt;, &lt;span class="s2"&gt;"ping"&lt;/span&gt;&lt;span class="o"&gt;]&lt;/span&gt;
      interval: 5s
      timeout: 5s
      retries: 5
    networks:
      - sure_net

volumes:
  app-storage:
  postgres-data:
  redis-data:

networks:
  sure_net:
    driver: bridge
EOF
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Now write &lt;code&gt;.env&lt;/code&gt;. Generate the secrets first:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;openssl rand -hex 64   &lt;span class="c"&gt;# SECRET_KEY_BASE&lt;/span&gt;
openssl rand -hex 32   &lt;span class="c"&gt;# POSTGRES_PASSWORD&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;





&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;cat &lt;span class="o"&gt;&amp;lt;&amp;lt;&lt;/span&gt;&lt;span class="s1"&gt;'EOF'&lt;/span&gt; &lt;span class="o"&gt;&amp;gt;&lt;/span&gt; .env
&lt;span class="nv"&gt;SECRET_KEY_BASE&lt;/span&gt;&lt;span class="o"&gt;=&amp;lt;&lt;/span&gt;paste the 128-char hex string&lt;span class="o"&gt;&amp;gt;&lt;/span&gt;
&lt;span class="nv"&gt;POSTGRES_USER&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;sure_user
&lt;span class="nv"&gt;POSTGRES_PASSWORD&lt;/span&gt;&lt;span class="o"&gt;=&amp;lt;&lt;/span&gt;paste the 64-char hex string&lt;span class="o"&gt;&amp;gt;&lt;/span&gt;
&lt;span class="nv"&gt;POSTGRES_DB&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;sure_production
&lt;span class="nv"&gt;PORT&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;3000
&lt;span class="nv"&gt;APP_DOMAIN&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;sure.example.com
&lt;span class="nv"&gt;ONBOARDING_STATE&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;open
&lt;span class="nv"&gt;SURE_IMAGE_TAG&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;stable

&lt;span class="c"&gt;# Optional: SMTP for password resets and rule notifications&lt;/span&gt;
&lt;span class="nv"&gt;SMTP_ADDRESS&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;
&lt;span class="nv"&gt;SMTP_PORT&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;465
&lt;span class="nv"&gt;SMTP_USERNAME&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;
&lt;span class="nv"&gt;SMTP_PASSWORD&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;
&lt;span class="nv"&gt;SMTP_TLS_ENABLED&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="kc"&gt;true&lt;/span&gt;
&lt;span class="nv"&gt;EMAIL_SENDER&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;sure@example.com

&lt;span class="c"&gt;# Optional: AI features (OpenAI-compatible endpoint)&lt;/span&gt;
&lt;span class="nv"&gt;OPENAI_ACCESS_TOKEN&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;
&lt;span class="nv"&gt;OPENAI_MODEL&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;
&lt;span class="nv"&gt;OPENAI_URI_BASE&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;
EOF
chmod 600 .env
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Start the stack:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;docker compose up -d
docker compose logs -f web
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The first boot runs database migrations. Wait until the logs settle, then open &lt;code&gt;http://127.0.0.1:3000&lt;/code&gt; from the host (or via an SSH tunnel: &lt;code&gt;ssh -L 3000:127.0.0.1:3000 user@vps&lt;/code&gt;).&lt;/p&gt;

&lt;h2&gt;
  
  
  Reverse proxy, HTTPS, and first-run hardening
&lt;/h2&gt;

&lt;p&gt;Sure runs plain HTTP inside the container. Your proxy terminates TLS and forwards to &lt;code&gt;127.0.0.1:3000&lt;/code&gt;. Because &lt;code&gt;RAILS_ASSUME_SSL&lt;/code&gt; is set to &lt;code&gt;true&lt;/code&gt;, the app builds HTTPS URLs and sets secure cookies correctly.&lt;/p&gt;

&lt;p&gt;Caddy example (&lt;code&gt;/etc/caddy/Caddyfile&lt;/code&gt;):&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight go"&gt;&lt;code&gt;&lt;span class="n"&gt;sure&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;example&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;com&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="n"&gt;encode&lt;/span&gt; &lt;span class="n"&gt;gzip&lt;/span&gt;
    &lt;span class="n"&gt;reverse_proxy&lt;/span&gt; &lt;span class="mf"&gt;127.0&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="mf"&gt;0.1&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="mi"&gt;3000&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
        &lt;span class="n"&gt;header_up&lt;/span&gt; &lt;span class="no"&gt;X&lt;/span&gt;&lt;span class="o"&gt;-&lt;/span&gt;&lt;span class="nc"&gt;Forwarded&lt;/span&gt;&lt;span class="o"&gt;-&lt;/span&gt;&lt;span class="nc"&gt;Proto&lt;/span&gt; &lt;span class="n"&gt;https&lt;/span&gt;
        &lt;span class="n"&gt;header_up&lt;/span&gt; &lt;span class="no"&gt;X&lt;/span&gt;&lt;span class="o"&gt;-&lt;/span&gt;&lt;span class="nc"&gt;Forwarded&lt;/span&gt;&lt;span class="o"&gt;-&lt;/span&gt;&lt;span class="nc"&gt;For&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;&lt;span class="n"&gt;remote_host&lt;/span&gt;&lt;span class="p"&gt;}&lt;/span&gt;
    &lt;span class="p"&gt;}&lt;/span&gt;
    &lt;span class="n"&gt;request_body&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
        &lt;span class="n"&gt;max_size&lt;/span&gt; &lt;span class="mi"&gt;100MB&lt;/span&gt;
    &lt;span class="p"&gt;}&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Nginx equivalent:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight nginx"&gt;&lt;code&gt;&lt;span class="n"&gt;server&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="n"&gt;listen&lt;/span&gt; &lt;span class="mi"&gt;443&lt;/span&gt; &lt;span class="n"&gt;ssl&lt;/span&gt; &lt;span class="n"&gt;http2&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
    &lt;span class="n"&gt;server_name&lt;/span&gt; &lt;span class="n"&gt;sure&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;example&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;com&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
    &lt;span class="n"&gt;client_max_body_size&lt;/span&gt; &lt;span class="mi"&gt;100M&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

    &lt;span class="n"&gt;location&lt;/span&gt; &lt;span class="o"&gt;/&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
        &lt;span class="n"&gt;proxy_pass&lt;/span&gt; &lt;span class="n"&gt;http&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="c1"&gt;//127.0.0.1:3000;&lt;/span&gt;
        &lt;span class="n"&gt;proxy_set_header&lt;/span&gt; &lt;span class="nc"&gt;Host&lt;/span&gt; $&lt;span class="n"&gt;host&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
        &lt;span class="n"&gt;proxy_set_header&lt;/span&gt; &lt;span class="no"&gt;X&lt;/span&gt;&lt;span class="o"&gt;-&lt;/span&gt;&lt;span class="nc"&gt;Real&lt;/span&gt;&lt;span class="o"&gt;-&lt;/span&gt;&lt;span class="no"&gt;IP&lt;/span&gt; $&lt;span class="n"&gt;remote_addr&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
        &lt;span class="n"&gt;proxy_set_header&lt;/span&gt; &lt;span class="no"&gt;X&lt;/span&gt;&lt;span class="o"&gt;-&lt;/span&gt;&lt;span class="nc"&gt;Forwarded&lt;/span&gt;&lt;span class="o"&gt;-&lt;/span&gt;&lt;span class="nc"&gt;For&lt;/span&gt; $&lt;span class="n"&gt;proxy_add_x_forwarded_for&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
        &lt;span class="n"&gt;proxy_set_header&lt;/span&gt; &lt;span class="no"&gt;X&lt;/span&gt;&lt;span class="o"&gt;-&lt;/span&gt;&lt;span class="nc"&gt;Forwarded&lt;/span&gt;&lt;span class="o"&gt;-&lt;/span&gt;&lt;span class="nc"&gt;Proto&lt;/span&gt; &lt;span class="n"&gt;https&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
        &lt;span class="n"&gt;proxy_read_timeout&lt;/span&gt; &lt;span class="mi"&gt;300s&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
    &lt;span class="p"&gt;}&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Notes specific to Sure:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;Upload size.&lt;/strong&gt; PDF imports and attachments go through the web app. Set &lt;code&gt;client_max_body_size&lt;/code&gt; (Nginx) or &lt;code&gt;request_body max_size&lt;/code&gt; (Caddy) to at least 100 MB, or imports fail with a 413.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Long requests.&lt;/strong&gt; AI chat turns can take up to &lt;code&gt;AI_RESPONSE_TIMEOUT&lt;/code&gt; seconds (default 90). Raise &lt;code&gt;proxy_read_timeout&lt;/code&gt; accordingly if you use the assistant.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;First-run signup.&lt;/strong&gt; With &lt;code&gt;ONBOARDING_STATE=open&lt;/code&gt;, the first visitor can create an account. Register your admin account immediately after the stack is healthy, then set &lt;code&gt;ONBOARDING_STATE=closed&lt;/code&gt; in &lt;code&gt;.env&lt;/code&gt; and run &lt;code&gt;docker compose up -d&lt;/code&gt; to restart with the new value. Leaving it open on a public domain lets strangers register.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Email confirmation.&lt;/strong&gt; If you enable "Require email confirmation" under Settings &amp;gt; Self-Hosting, SMTP must be configured on the &lt;strong&gt;worker&lt;/strong&gt; service — that's where mail is sent from. Invitations are never emailed on self-hosted instances; copy the invite link from Settings &amp;gt; Profile Info and send it yourself.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;WebAuthn/passkeys.&lt;/strong&gt; If you enable passkey login, set &lt;code&gt;WEBAUTHN_RP_ID&lt;/code&gt; to your bare domain (e.g. &lt;code&gt;sure.example.com&lt;/code&gt;) and &lt;code&gt;WEBAUTHN_ALLOWED_ORIGINS&lt;/code&gt; to the full origin (e.g. &lt;code&gt;https://sure.example.com&lt;/code&gt;).&lt;/li&gt;
&lt;/ul&gt;

&lt;h2&gt;
  
  
  Updating, backups, and common pitfalls
&lt;/h2&gt;

&lt;p&gt;&lt;strong&gt;Update:&lt;/strong&gt;&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;&lt;span class="nb"&gt;cd&lt;/span&gt; ~/docker-apps/sure
docker compose pull
docker compose up -d
docker compose logs -f web
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Migrations run on boot. Pin &lt;code&gt;SURE_IMAGE_TAG&lt;/code&gt; to a specific release if you want to control when upgrades land.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Backups.&lt;/strong&gt; The official compose file ships a &lt;code&gt;backup&lt;/code&gt; service that captures the database, &lt;code&gt;app-storage&lt;/code&gt;, &lt;code&gt;.env&lt;/code&gt;, and &lt;code&gt;compose.yml&lt;/code&gt; into &lt;code&gt;./backups/&amp;lt;version&amp;gt;/&amp;lt;timestamp&amp;gt;-&amp;lt;trigger&amp;gt;/&lt;/code&gt;. Add it to your compose file from the upstream example, then:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;docker compose --profile backup run --rm backup create
docker compose --profile backup up -d backup   &lt;span class="c"&gt;# daily at 02:00 by default&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;If you prefer manual backups, dump the two volumes that matter:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;docker compose &lt;span class="nb"&gt;exec&lt;/span&gt; -T db pg_dump -U sure_user sure_production &lt;span class="o"&gt;|&lt;/span&gt; gzip &lt;span class="o"&gt;&amp;gt;&lt;/span&gt; sure-db-&lt;span class="nv"&gt;$(&lt;/span&gt;date +%F&lt;span class="o"&gt;)&lt;/span&gt;.sql.gz
docker run --rm -v sure_app-storage:/data -v &lt;span class="s2"&gt;"$PWD"&lt;/span&gt;:/backup alpine tar czf /backup/sure-storage-&lt;span class="nv"&gt;$(&lt;/span&gt;date +%F&lt;span class="o"&gt;)&lt;/span&gt;.tar.gz -C /data .
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Restore by piping the dump back into &lt;code&gt;psql&lt;/code&gt; and untarring into &lt;code&gt;app-storage&lt;/code&gt; while the stack is stopped.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Pitfalls from the docs:&lt;/strong&gt;&lt;/p&gt;

&lt;ol&gt;
&lt;li&gt;
&lt;strong&gt;Yahoo Finance IPv6 hangs.&lt;/strong&gt; If market data sync fails with &lt;code&gt;Failed to open TCP connection&lt;/code&gt; to &lt;code&gt;fc.yahoo.com&lt;/code&gt;, DNS is resolving to IPv6 inside the container and the connection hangs. The compose file already sets &lt;code&gt;dns: [8.8.8.8, 1.1.1.1]&lt;/code&gt;; if that isn't enough, add &lt;code&gt;extra_hosts&lt;/code&gt; entries pinning the IPv4 addresses, or switch &lt;code&gt;EXCHANGE_RATE_PROVIDER&lt;/code&gt;/&lt;code&gt;SECURITIES_PROVIDER&lt;/code&gt; to a provider with an API key (e.g. Twelve Data).&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Rotating &lt;code&gt;SECRET_KEY_BASE&lt;/code&gt; breaks encrypted data.&lt;/strong&gt; Provider API tokens and other sensitive fields are encrypted with keys derived from &lt;code&gt;SECRET_KEY_BASE&lt;/code&gt; when &lt;code&gt;ACTIVE_RECORD_ENCRYPTION_*&lt;/code&gt; are unset. If you set the three &lt;code&gt;ACTIVE_RECORD_ENCRYPTION_*&lt;/code&gt; variables explicitly, set all three or none — adding them to an instance that already has data changes its keys and makes existing encrypted fields unreadable. Back up &lt;code&gt;.env&lt;/code&gt; alongside the database so you can restore the exact key set.&lt;/li&gt;
&lt;/ol&gt;




&lt;p&gt;&lt;strong&gt;Measured in our sandbox run:&lt;/strong&gt; total memory 798.3 MB (sum of per-container peaks over a 30s idle window after startup) across 4 containers; largest container 381.1 MB; published port(s) 3000; HTTP probe returned 302. The run took 77.6s including the image download. Required secret(s) APP_DOMAIN, POSTGRES_PASSWORD, SECRET_KEY_BASE were generated for the test run, as the tutorial instructs. Container breakdown: web 381.1 MB, worker 367.7 MB, db 39.0 MB, redis 10.5 MB.&lt;/p&gt;




&lt;p&gt;&lt;em&gt;Verification: we ran this docker-compose stack in a disposable Docker environment and recorded the measurements above. They describe that run, not a guarantee for your host.&lt;/em&gt;&lt;/p&gt;




&lt;p&gt;&lt;em&gt;Originally published with full interactive benchmark metrics and server sizing notes at &lt;a href="https://benchrun.pages.dev/self-host-sure-docker-vps/" rel="noopener noreferrer"&gt;https://benchrun.pages.dev/self-host-sure-docker-vps/&lt;/a&gt;.&lt;/em&gt;&lt;/p&gt;

</description>
      <category>finance</category>
      <category>docker</category>
      <category>rails</category>
      <category>selfhosting</category>
    </item>
    <item>
      <title>How to Self-Host Uptime Kuma on a VPS with Docker (2026 Guide)</title>
      <dc:creator>konsongong</dc:creator>
      <pubDate>Mon, 16 Nov 2026 11:30:52 +0000</pubDate>
      <link>https://dev.to/gongkang/how-to-self-host-uptime-kuma-on-a-vps-with-docker-2026-guide-nd6</link>
      <guid>https://dev.to/gongkang/how-to-self-host-uptime-kuma-on-a-vps-with-docker-2026-guide-nd6</guid>
      <description>&lt;blockquote&gt;
&lt;p&gt;This tutorial was written with AI assistance from the project's official documentation. Verification status is stated at the end of the article.&lt;/p&gt;
&lt;/blockquote&gt;

&lt;h2&gt;
  
  
  What is Uptime Kuma and why self-host it
&lt;/h2&gt;

&lt;p&gt;Uptime Kuma is a self-hosted monitoring tool with a reactive web UI. It checks HTTP(s) endpoints, TCP ports, HTTP(s) keyword and JSON query responses, WebSockets, ping, DNS records, push heartbeats, Steam game servers and Docker containers. Checks run on a 20-second interval by default, and you can wire alerts into Telegram, Discord, Gotify, Slack, Pushover, SMTP email and a long list of other notification services.&lt;/p&gt;

&lt;p&gt;Self-hosting it means your uptime history, monitor definitions and notification credentials stay on hardware you control. You also get multiple status pages that can be mapped to specific domains, ping charts, TLS certificate info, proxy support and 2FA on the login. The project does not publish a memory requirement, so size the VPS against how many monitors you plan to run rather than a documented figure.&lt;/p&gt;

&lt;h2&gt;
  
  
  Prerequisites and server setup
&lt;/h2&gt;

&lt;p&gt;You need a Linux VPS with a public IP, Docker Engine and the Docker Compose plugin installed. Confirm both are present:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;docker --version
docker compose version
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Open port 3001 in your firewall if you want to reach the UI directly before adding a reverse proxy, and open 80/443 for the proxy later. Uptime Kuma stores its SQLite database and uploaded assets under &lt;code&gt;/app/data&lt;/code&gt; inside the container, so that path must be backed by a persistent volume.&lt;/p&gt;

&lt;p&gt;One important constraint from the README: NFS (Network File System) mounts are &lt;strong&gt;not&lt;/strong&gt; supported. Map &lt;code&gt;/app/data&lt;/code&gt; to a local directory or a Docker-managed volume, not to a network share.&lt;/p&gt;

&lt;h2&gt;
  
  
  Step-by-step installation with Docker
&lt;/h2&gt;

&lt;p&gt;The README ships a &lt;code&gt;compose.yaml&lt;/code&gt; you can download directly, but the equivalent minimal configuration below is what you want on a fresh VPS. It pins the &lt;code&gt;2&lt;/code&gt; image tag used in the official &lt;code&gt;docker run&lt;/code&gt; example, publishes port 3001, and keeps data in a named volume.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight yaml"&gt;&lt;code&gt;&lt;span class="na"&gt;services&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
  &lt;span class="na"&gt;uptime-kuma&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
    &lt;span class="na"&gt;image&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s"&gt;louislam/uptime-kuma:2&lt;/span&gt;
    &lt;span class="na"&gt;container_name&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s"&gt;uptime-kuma&lt;/span&gt;
    &lt;span class="na"&gt;restart&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s"&gt;always&lt;/span&gt;
    &lt;span class="na"&gt;ports&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
      &lt;span class="p"&gt;-&lt;/span&gt; &lt;span class="s2"&gt;"3001:3001"&lt;/span&gt;
    &lt;span class="na"&gt;volumes&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
      &lt;span class="p"&gt;-&lt;/span&gt; &lt;span class="s"&gt;uptime-kuma:/app/data&lt;/span&gt;

&lt;span class="na"&gt;volumes&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
  &lt;span class="na"&gt;uptime-kuma&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Save that as &lt;code&gt;compose.yaml&lt;/code&gt; in a directory such as &lt;code&gt;~/uptime-kuma&lt;/code&gt;, then start it:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;mkdir -p ~/uptime-kuma
&lt;span class="nb"&gt;cd&lt;/span&gt; ~/uptime-kuma
&lt;span class="c"&gt;# write compose.yaml here&lt;/span&gt;
docker compose up -d
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Check that the container came up cleanly:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;docker compose ps
docker compose logs -f uptime-kuma
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Uptime Kuma does not require any environment variables to boot. The README documents no env vars for the Docker image, so there is no &lt;code&gt;.env&lt;/code&gt; file to create for a basic install. If you prefer to bind-mount a host directory instead of a named volume, replace the volume line with something like &lt;code&gt;- ./data:/app/data&lt;/code&gt; — just keep it on local disk, not NFS.&lt;/p&gt;

&lt;p&gt;If you want the container reachable only from the host (for example, behind a proxy on the same machine), change the port mapping to &lt;code&gt;127.0.0.1:3001:3001&lt;/code&gt; as shown in the README's localhost-only example.&lt;/p&gt;

&lt;h2&gt;
  
  
  Accessing the dashboard and reverse proxy
&lt;/h2&gt;

&lt;p&gt;Once the container is running, open &lt;code&gt;http://your-server-ip:3001&lt;/code&gt;. On first load you are asked to create an admin username and password. After that, add monitors from the dashboard, configure notifications under Settings, and build status pages.&lt;/p&gt;

&lt;p&gt;For anything beyond a quick test, put HTTPS in front of it. With Caddy on the same host, a &lt;code&gt;Caddyfile&lt;/code&gt; entry is enough:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight nginx"&gt;&lt;code&gt;&lt;span class="n"&gt;status&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;example&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;com&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="n"&gt;reverse_proxy&lt;/span&gt; &lt;span class="mf"&gt;127.0&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="mf"&gt;0.1&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="mi"&gt;3001&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;If you use Nginx Proxy Manager instead, create a proxy host pointing at the container's host IP and port &lt;code&gt;3001&lt;/code&gt;, enable WebSockets support (Uptime Kuma's UI uses WebSocket for live updates), and request a Let's Encrypt certificate from the SSL tab. The README points to the wiki's installation page for reverse-proxy specifics, so check there if your setup needs extra headers.&lt;/p&gt;

&lt;h2&gt;
  
  
  Wrapping up
&lt;/h2&gt;

&lt;p&gt;Uptime Kuma gives you a full monitoring stack — checks, notifications, status pages and 2FA — in a single container with one persistent volume. The source, release notes and update instructions live at &lt;a href="https://github.com/louislam/uptime-kuma" rel="noopener noreferrer"&gt;github.com/louislam/uptime-kuma&lt;/a&gt;.&lt;/p&gt;




&lt;p&gt;&lt;strong&gt;Measured in our sandbox run:&lt;/strong&gt; total memory 206.5 MB (sum of per-container peaks over a 30s idle window after startup) across 1 container; largest container 206.5 MB; published port(s) 3001; HTTP probe returned 200. The run took 43.0s with the image already cached; a fresh server also has to download it.&lt;/p&gt;




&lt;p&gt;&lt;em&gt;Verification: we ran this docker-compose stack in a disposable Docker environment and recorded the measurements above. They describe that run, not a guarantee for your host.&lt;/em&gt;&lt;/p&gt;




&lt;p&gt;&lt;em&gt;Originally published with full interactive benchmark metrics and server sizing notes at &lt;a href="https://benchrun.pages.dev/self-host-uptime-kuma-docker-vps/" rel="noopener noreferrer"&gt;https://benchrun.pages.dev/self-host-uptime-kuma-docker-vps/&lt;/a&gt;.&lt;/em&gt;&lt;/p&gt;

</description>
      <category>uptimekuma</category>
      <category>monitoring</category>
      <category>docker</category>
      <category>selfhosting</category>
    </item>
    <item>
      <title>Self-Host n8n with Docker Compose: Production Setup Guide</title>
      <dc:creator>konsongong</dc:creator>
      <pubDate>Mon, 16 Nov 2026 11:30:28 +0000</pubDate>
      <link>https://dev.to/gongkang/how-to-self-host-n8n-on-a-vps-with-docker-2026-guide-30da</link>
      <guid>https://dev.to/gongkang/how-to-self-host-n8n-on-a-vps-with-docker-2026-guide-30da</guid>
      <description>&lt;blockquote&gt;
&lt;p&gt;This tutorial was written with AI assistance from the project's official documentation. Verification status is stated at the end of the article.&lt;/p&gt;
&lt;/blockquote&gt;

&lt;h2&gt;
  
  
  What n8n does and what it needs
&lt;/h2&gt;

&lt;p&gt;n8n is a fair-code workflow automation platform with a visual canvas, 1500+ integrations, and native AI agent support. You build workflows by wiring nodes together, drop into JavaScript or Python when the visual editor runs out, and schedule or trigger runs via webhooks, cron, or app events. Self-hosting gives you full control over credentials, execution data, and outbound network access — useful when workflows touch internal systems or sensitive data.&lt;/p&gt;

&lt;p&gt;The official Docker Compose example runs a single &lt;code&gt;n8nio/n8n&lt;/code&gt; container backed by a named volume for the SQLite database and encryption key. That is the simplest production shape and what this guide uses. The upstream project does not publish a minimum memory figure. Practical sizing depends on workload: an idle instance with a handful of scheduled workflows is light, while heavy AI nodes, large file transfers, and high-frequency webhooks push both RAM and CPU. Watch container memory during the first week and scale the VPS if you see sustained pressure.&lt;/p&gt;

&lt;h2&gt;
  
  
  Prerequisites, ports, and volume constraints
&lt;/h2&gt;

&lt;ul&gt;
&lt;li&gt;A Linux server with Docker Engine and the Compose plugin (&lt;code&gt;docker --version&lt;/code&gt;, &lt;code&gt;docker compose version&lt;/code&gt;).&lt;/li&gt;
&lt;li&gt;A DNS A record for the subdomain you will use (for example &lt;code&gt;n8n.example.com&lt;/code&gt;) pointing at the server IP.&lt;/li&gt;
&lt;li&gt;Port &lt;code&gt;5678&lt;/code&gt; is the n8n HTTP port. In this setup it binds to &lt;code&gt;127.0.0.1:5678&lt;/code&gt; only, so a reverse proxy on the same host terminates TLS.&lt;/li&gt;
&lt;li&gt;One named volume, &lt;code&gt;n8n_data&lt;/code&gt;, mounted at &lt;code&gt;/home/node/.n8n&lt;/code&gt;. It holds the SQLite database and the encryption key that protects stored credentials. Lose it and you lose every saved credential.&lt;/li&gt;
&lt;li&gt;An optional bind mount for file nodes. Create &lt;code&gt;./local-files&lt;/code&gt; on the host and mount it at &lt;code&gt;/files&lt;/code&gt;; set &lt;code&gt;N8N_RESTRICT_FILE_ACCESS_TO=/files&lt;/code&gt; so the Read/Write Files node cannot wander outside that directory.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;If you are testing without a domain, either SSH-tunnel to the loopback port (&lt;code&gt;ssh -L 5678:127.0.0.1:5678 user@server&lt;/code&gt;) or temporarily change the port mapping to &lt;code&gt;5678:5678&lt;/code&gt; and open the firewall for your IP only. Do not leave it publicly exposed without TLS.&lt;/p&gt;

&lt;h2&gt;
  
  
  Production Docker Compose setup
&lt;/h2&gt;

&lt;p&gt;Create the project directory and the file-share directory first:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;mkdir -p ~/n8n-compose/local-files
&lt;span class="nb"&gt;cd&lt;/span&gt; ~/n8n-compose
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Write the Compose file. It runs only n8n; the reverse proxy lives outside this stack so the app boots standalone.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;cat &lt;span class="o"&gt;&amp;lt;&amp;lt;&lt;/span&gt;&lt;span class="s1"&gt;'EOF'&lt;/span&gt; &lt;span class="o"&gt;&amp;gt;&lt;/span&gt; compose.yml
services:
  n8n:
    image: docker.n8n.io/n8nio/n8n:&lt;span class="nv"&gt;${N8N_VERSION:-stable}&lt;/span&gt;
    restart: unless-stopped
    ports:
      - &lt;span class="s2"&gt;"127.0.0.1:5678:5678"&lt;/span&gt;
    environment:
      - &lt;span class="nv"&gt;N8N_HOST&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="nv"&gt;${N8N_HOST}&lt;/span&gt;
      - &lt;span class="nv"&gt;N8N_PORT&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;5678
      - &lt;span class="nv"&gt;N8N_PROTOCOL&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;https
      - &lt;span class="nv"&gt;NODE_ENV&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;production
      - &lt;span class="nv"&gt;N8N_WEBHOOK_URL&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;https://&lt;span class="nv"&gt;${N8N_HOST}&lt;/span&gt;/
      - &lt;span class="nv"&gt;GENERIC_TIMEZONE&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="nv"&gt;${GENERIC_TIMEZONE:-UTC}&lt;/span&gt;
      - &lt;span class="nv"&gt;TZ&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="nv"&gt;${GENERIC_TIMEZONE:-UTC}&lt;/span&gt;
      - &lt;span class="nv"&gt;N8N_ENFORCE_SETTINGS_FILE_PERMISSIONS&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="kc"&gt;true&lt;/span&gt;
      - &lt;span class="nv"&gt;N8N_RESTRICT_FILE_ACCESS_TO&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;/files
    volumes:
      - n8n_data:/home/node/.n8n
      - ./local-files:/files

volumes:
  n8n_data:
EOF
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Now the &lt;code&gt;.env&lt;/code&gt;. Generate a strong encryption key with &lt;code&gt;openssl rand -hex 32&lt;/code&gt; and paste it into &lt;code&gt;N8N_ENCRYPTION_KEY&lt;/code&gt;. Keep that value somewhere safe — if you ever recreate the volume without it, stored credentials become unreadable.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;cat &lt;span class="o"&gt;&amp;lt;&amp;lt;&lt;/span&gt;&lt;span class="s1"&gt;'EOF'&lt;/span&gt; &lt;span class="o"&gt;&amp;gt;&lt;/span&gt; .env
&lt;span class="c"&gt;# Public hostname n8n will be served from (no scheme)&lt;/span&gt;
&lt;span class="nv"&gt;N8N_HOST&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;n8n.example.com

&lt;span class="c"&gt;# Timezone used by Cron and scheduling nodes&lt;/span&gt;
&lt;span class="nv"&gt;GENERIC_TIMEZONE&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;UTC

&lt;span class="c"&gt;# Pin to a specific release for reproducible deploys, or leave as stable&lt;/span&gt;
&lt;span class="nv"&gt;N8N_VERSION&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;stable

&lt;span class="c"&gt;# 64-char hex key that encrypts stored credentials. Generate once, back it up.&lt;/span&gt;
&lt;span class="nv"&gt;N8N_ENCRYPTION_KEY&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;replace-with-openssl-rand-hex-32
EOF
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Start the stack:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;docker compose up -d
docker compose logs -f n8n
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;You should see n8n report that the editor is ready on port 5678. It is not reachable from the internet yet — that is the next step.&lt;/p&gt;

&lt;h2&gt;
  
  
  Reverse proxy, HTTPS, and first-run hardening
&lt;/h2&gt;

&lt;p&gt;n8n needs a proxy that forwards the original host and protocol, because it builds webhook URLs and OAuth callbacks from &lt;code&gt;N8N_HOST&lt;/code&gt; and &lt;code&gt;N8N_WEBHOOK_URL&lt;/code&gt;. If those are wrong, every webhook trigger silently points at the wrong place.&lt;/p&gt;

&lt;p&gt;Caddy example (&lt;code&gt;/etc/caddy/Caddyfile&lt;/code&gt;):&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight nginx"&gt;&lt;code&gt;&lt;span class="n"&gt;n8n&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;example&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;com&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="n"&gt;encode&lt;/span&gt; &lt;span class="n"&gt;zstd&lt;/span&gt; &lt;span class="n"&gt;gzip&lt;/span&gt;
    &lt;span class="n"&gt;reverse_proxy&lt;/span&gt; &lt;span class="mf"&gt;127.0&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="mf"&gt;0.1&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="mi"&gt;5678&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
        &lt;span class="n"&gt;header_up&lt;/span&gt; &lt;span class="no"&gt;X&lt;/span&gt;&lt;span class="o"&gt;-&lt;/span&gt;&lt;span class="nc"&gt;Forwarded&lt;/span&gt;&lt;span class="o"&gt;-&lt;/span&gt;&lt;span class="nc"&gt;Proto&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;&lt;span class="n"&gt;scheme&lt;/span&gt;&lt;span class="p"&gt;}&lt;/span&gt;
        &lt;span class="n"&gt;header_up&lt;/span&gt; &lt;span class="no"&gt;X&lt;/span&gt;&lt;span class="o"&gt;-&lt;/span&gt;&lt;span class="nc"&gt;Forwarded&lt;/span&gt;&lt;span class="o"&gt;-&lt;/span&gt;&lt;span class="nc"&gt;Host&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;&lt;span class="n"&gt;host&lt;/span&gt;&lt;span class="p"&gt;}&lt;/span&gt;
    &lt;span class="p"&gt;}&lt;/span&gt;
    &lt;span class="n"&gt;request_body&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
        &lt;span class="n"&gt;max_size&lt;/span&gt; &lt;span class="mi"&gt;100MB&lt;/span&gt;
    &lt;span class="p"&gt;}&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Nginx equivalent:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight nginx"&gt;&lt;code&gt;&lt;span class="n"&gt;server&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="n"&gt;listen&lt;/span&gt; &lt;span class="mi"&gt;443&lt;/span&gt; &lt;span class="n"&gt;ssl&lt;/span&gt; &lt;span class="n"&gt;http2&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
    &lt;span class="n"&gt;server_name&lt;/span&gt; &lt;span class="n"&gt;n8n&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;example&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;com&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

    &lt;span class="n"&gt;ssl_certificate&lt;/span&gt;     &lt;span class="o"&gt;/&lt;/span&gt;&lt;span class="n"&gt;etc&lt;/span&gt;&lt;span class="o"&gt;/&lt;/span&gt;&lt;span class="n"&gt;letsencrypt&lt;/span&gt;&lt;span class="o"&gt;/&lt;/span&gt;&lt;span class="n"&gt;live&lt;/span&gt;&lt;span class="o"&gt;/&lt;/span&gt;&lt;span class="n"&gt;n8n&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;example&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;com&lt;/span&gt;&lt;span class="o"&gt;/&lt;/span&gt;&lt;span class="n"&gt;fullchain&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;pem&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
    &lt;span class="n"&gt;ssl_certificate_key&lt;/span&gt; &lt;span class="o"&gt;/&lt;/span&gt;&lt;span class="n"&gt;etc&lt;/span&gt;&lt;span class="o"&gt;/&lt;/span&gt;&lt;span class="n"&gt;letsencrypt&lt;/span&gt;&lt;span class="o"&gt;/&lt;/span&gt;&lt;span class="n"&gt;live&lt;/span&gt;&lt;span class="o"&gt;/&lt;/span&gt;&lt;span class="n"&gt;n8n&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;example&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;com&lt;/span&gt;&lt;span class="o"&gt;/&lt;/span&gt;&lt;span class="n"&gt;privkey&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;pem&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

    &lt;span class="n"&gt;client_max_body_size&lt;/span&gt; &lt;span class="mi"&gt;100M&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

    &lt;span class="n"&gt;location&lt;/span&gt; &lt;span class="o"&gt;/&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
        &lt;span class="n"&gt;proxy_pass&lt;/span&gt; &lt;span class="n"&gt;http&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="c1"&gt;//127.0.0.1:5678;&lt;/span&gt;
        &lt;span class="n"&gt;proxy_http_version&lt;/span&gt; &lt;span class="mf"&gt;1.1&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
        &lt;span class="n"&gt;proxy_set_header&lt;/span&gt; &lt;span class="nc"&gt;Host&lt;/span&gt; $&lt;span class="n"&gt;host&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
        &lt;span class="n"&gt;proxy_set_header&lt;/span&gt; &lt;span class="no"&gt;X&lt;/span&gt;&lt;span class="o"&gt;-&lt;/span&gt;&lt;span class="nc"&gt;Real&lt;/span&gt;&lt;span class="o"&gt;-&lt;/span&gt;&lt;span class="no"&gt;IP&lt;/span&gt; $&lt;span class="n"&gt;remote_addr&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
        &lt;span class="n"&gt;proxy_set_header&lt;/span&gt; &lt;span class="no"&gt;X&lt;/span&gt;&lt;span class="o"&gt;-&lt;/span&gt;&lt;span class="nc"&gt;Forwarded&lt;/span&gt;&lt;span class="o"&gt;-&lt;/span&gt;&lt;span class="nc"&gt;For&lt;/span&gt; $&lt;span class="n"&gt;proxy_add_x_forwarded_for&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
        &lt;span class="n"&gt;proxy_set_header&lt;/span&gt; &lt;span class="no"&gt;X&lt;/span&gt;&lt;span class="o"&gt;-&lt;/span&gt;&lt;span class="nc"&gt;Forwarded&lt;/span&gt;&lt;span class="o"&gt;-&lt;/span&gt;&lt;span class="nc"&gt;Proto&lt;/span&gt; $&lt;span class="n"&gt;scheme&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
        &lt;span class="n"&gt;proxy_set_header&lt;/span&gt; &lt;span class="nc"&gt;Upgrade&lt;/span&gt; $&lt;span class="n"&gt;http_upgrade&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
        &lt;span class="n"&gt;proxy_set_header&lt;/span&gt; &lt;span class="nc"&gt;Connection&lt;/span&gt; &lt;span class="s2"&gt;"upgrade"&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
        &lt;span class="n"&gt;proxy_read_timeout&lt;/span&gt; &lt;span class="mi"&gt;3600s&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
    &lt;span class="p"&gt;}&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The &lt;code&gt;Upgrade&lt;/code&gt;/&lt;code&gt;Connection&lt;/code&gt; headers and the long read timeout matter: the editor keeps a WebSocket open for live execution updates, and long-running workflows will drop the connection if the proxy times out at 60 seconds. The body size limit matters for file uploads and webhook payloads.&lt;/p&gt;

&lt;p&gt;First-run hardening:&lt;/p&gt;

&lt;ol&gt;
&lt;li&gt;Open &lt;code&gt;https://n8n.example.com&lt;/code&gt; and complete the owner account setup immediately. Until you do, anyone who reaches the URL can claim the instance.&lt;/li&gt;
&lt;li&gt;If you need to delay setup, keep the proxy disabled or block the port at the firewall until you are ready.&lt;/li&gt;
&lt;li&gt;Store API keys and OAuth secrets as n8n credentials, not in environment variables — they are encrypted with &lt;code&gt;N8N_ENCRYPTION_KEY&lt;/code&gt; and survive restarts.&lt;/li&gt;
&lt;li&gt;Restrict outbound traffic if workflows should only reach known APIs. n8n can call anything the container can reach.&lt;/li&gt;
&lt;/ol&gt;

&lt;h2&gt;
  
  
  Updating, backups, and common pitfalls
&lt;/h2&gt;

&lt;p&gt;Update to the latest stable release:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;&lt;span class="nb"&gt;cd&lt;/span&gt; ~/n8n-compose
docker compose pull
docker compose up -d
docker compose logs -f n8n
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;If you pinned &lt;code&gt;N8N_VERSION&lt;/code&gt;, bump it in &lt;code&gt;.env&lt;/code&gt; first. n8n ships a new minor version most weeks; read the release notes before jumping major versions, since node behavior and database migrations can change.&lt;/p&gt;

&lt;p&gt;Back up the volume and your &lt;code&gt;.env&lt;/code&gt; together — the encryption key in &lt;code&gt;.env&lt;/code&gt; is useless without the database, and vice versa:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;&lt;span class="nb"&gt;cd&lt;/span&gt; ~/n8n-compose
docker compose stop n8n
docker run --rm \
  -v n8n-compose_n8n_data:/data \
  -v &lt;span class="s2"&gt;"$PWD"&lt;/span&gt;:/backup \
  alpine tar czf /backup/n8n-data-&lt;span class="nv"&gt;$(&lt;/span&gt;date +%F&lt;span class="o"&gt;)&lt;/span&gt;.tar.gz -C /data .
cp .env &lt;span class="s2"&gt;"backup/n8n-env-$(date +%F).env"&lt;/span&gt;
docker compose start n8n
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Adjust the volume name if your project directory is not &lt;code&gt;n8n-compose&lt;/code&gt;; check with &lt;code&gt;docker volume ls&lt;/code&gt;. Restore by stopping n8n, extracting the tarball back into the volume, and starting again.&lt;/p&gt;

&lt;p&gt;Two pitfalls worth knowing before you hit them:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;Webhook URL drift.&lt;/strong&gt; If &lt;code&gt;N8N_HOST&lt;/code&gt; or &lt;code&gt;N8N_WEBHOOK_URL&lt;/code&gt; is wrong, the editor still works but every webhook trigger and OAuth redirect points at the wrong host. After changing either value, restart the container and re-check the webhook URL shown in the node panel.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;File access scope.&lt;/strong&gt; &lt;code&gt;N8N_RESTRICT_FILE_ACCESS_TO=/files&lt;/code&gt; limits the Read/Write Files node to the mounted directory. If you skip it, workflows can read and write anywhere the container user can reach, including the SQLite database and encryption key. Keep the restriction and put shared files under &lt;code&gt;./local-files&lt;/code&gt;.&lt;/li&gt;
&lt;/ul&gt;




&lt;p&gt;&lt;strong&gt;Measured in our sandbox run:&lt;/strong&gt; total memory 638.3 MB (sum of per-container peaks over a 30s idle window after startup) across 1 container; largest container 638.3 MB; published port(s) 5678; HTTP probe returned 200. The run took 37.9s with the image already cached; a fresh server also has to download it. Required secret(s) N8N_HOST were generated for the test run, as the tutorial instructs.&lt;/p&gt;




&lt;p&gt;&lt;em&gt;Verification: we ran this docker-compose stack in a disposable Docker environment and recorded the measurements above. They describe that run, not a guarantee for your host.&lt;/em&gt;&lt;/p&gt;




&lt;p&gt;&lt;em&gt;Originally published with full interactive benchmark metrics and server sizing notes at &lt;a href="https://benchrun.pages.dev/self-host-n8n-docker-vps/" rel="noopener noreferrer"&gt;https://benchrun.pages.dev/self-host-n8n-docker-vps/&lt;/a&gt;.&lt;/em&gt;&lt;/p&gt;

</description>
      <category>n8n</category>
      <category>docker</category>
      <category>workflowautomation</category>
      <category>selfhosting</category>
    </item>
  </channel>
</rss>
