<?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: Amritasha Agrawal</title>
    <description>The latest articles on DEV Community by Amritasha Agrawal (@amritasha_agrawal_a297c7d).</description>
    <link>https://dev.to/amritasha_agrawal_a297c7d</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%2F3917308%2Fea282854-0699-4be0-9c92-17a4ccf23c35.png</url>
      <title>DEV Community: Amritasha Agrawal</title>
      <link>https://dev.to/amritasha_agrawal_a297c7d</link>
    </image>
    <atom:link rel="self" type="application/rss+xml" href="https://dev.to/feed/amritasha_agrawal_a297c7d"/>
    <language>en</language>
    <item>
      <title>Connect WhatsApp to Self-Hosted Chatwoot on Railway (Official Cloud API — Works on the Hobby Plan)</title>
      <dc:creator>Amritasha Agrawal</dc:creator>
      <pubDate>Wed, 11 Nov 2026 12:34:09 +0000</pubDate>
      <link>https://dev.to/amritasha_agrawal_a297c7d/connect-whatsapp-to-self-hosted-chatwoot-on-railway-official-cloud-api-works-on-the-hobby-plan-36h0</link>
      <guid>https://dev.to/amritasha_agrawal_a297c7d/connect-whatsapp-to-self-hosted-chatwoot-on-railway-official-cloud-api-works-on-the-hobby-plan-36h0</guid>
      <description>&lt;p&gt;WhatsApp is the reason a lot of teams self-host Chatwoot: one shared inbox where several agents answer the business number, with no per-seat fee. The official way to connect it is Meta's &lt;strong&gt;WhatsApp Cloud API&lt;/strong&gt;, which Chatwoot supports natively.&lt;/p&gt;

&lt;p&gt;Good news if you're on Railway's Hobby plan: unlike email, WhatsApp works there. Railway blocks outbound SMTP below Pro, but the Cloud API is plain HTTPS in both directions — Chatwoot calls Meta's Graph API, and Meta calls a webhook on your Chatwoot domain.&lt;/p&gt;

&lt;p&gt;This guide covers the setup and, more importantly, three self-hosting details that let Chatwoot show "connected" while incoming messages never appear.&lt;/p&gt;

&lt;h2&gt;
  
  
  Before you start
&lt;/h2&gt;

&lt;p&gt;You need:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;A &lt;strong&gt;self-hosted Chatwoot&lt;/strong&gt; reachable over public HTTPS (the default &lt;code&gt;*.up.railway.app&lt;/code&gt; domain is fine).&lt;/li&gt;
&lt;li&gt;A &lt;strong&gt;Meta Business portfolio&lt;/strong&gt; and a &lt;strong&gt;Meta developer app&lt;/strong&gt; with the WhatsApp use case.&lt;/li&gt;
&lt;li&gt;A &lt;strong&gt;phone number&lt;/strong&gt; that is &lt;em&gt;not&lt;/em&gt; currently active in the WhatsApp or WhatsApp Business phone app. Chatwoot's manual setup doesn't support coexistence with the app.&lt;/li&gt;
&lt;li&gt;Admin access in Chatwoot.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;Two things to know about the official API:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;The 24-hour window.&lt;/strong&gt; You can reply freely within 24 hours of the customer's last message. After that, Meta only lets you start the conversation again with an approved &lt;strong&gt;message template&lt;/strong&gt;. Chatwoot syncs approved templates from your WhatsApp Business Account automatically.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Unofficial bridges are a different thing.&lt;/strong&gt; Tools that drive WhatsApp Web (WAHA, Baileys-based APIs) skip Meta's approval process, but they're unofficial and numbers can get banned. This guide uses the official API only.&lt;/li&gt;
&lt;/ul&gt;

&lt;h2&gt;
  
  
  The three self-hosting details that break WhatsApp
&lt;/h2&gt;

&lt;h3&gt;
  
  
  1. &lt;code&gt;FRONTEND_URL&lt;/code&gt; becomes your webhook URL
&lt;/h3&gt;

&lt;p&gt;Chatwoot builds the WhatsApp webhook from &lt;code&gt;FRONTEND_URL&lt;/code&gt;:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;&amp;lt;FRONTEND_URL&amp;gt;/webhooks/whatsapp/&amp;lt;phone-number&amp;gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;and registers that URL with Meta when you create the inbox. If &lt;code&gt;FRONTEND_URL&lt;/code&gt; is wrong, empty, or still the Railway domain after you moved to a custom domain, Meta delivers messages to the wrong place and nothing arrives.&lt;/p&gt;

&lt;p&gt;Set &lt;code&gt;FRONTEND_URL&lt;/code&gt; to the public HTTPS URL agents actually use &lt;strong&gt;before&lt;/strong&gt; creating the inbox. If you change domains later, update &lt;code&gt;FRONTEND_URL&lt;/code&gt;, redeploy, and re-run the webhook setup from the inbox (or update the callback URL in your Meta app).&lt;/p&gt;

&lt;h3&gt;
  
  
  2. Sidekiq must be running
&lt;/h3&gt;

&lt;p&gt;When Meta calls the webhook, Chatwoot's web server accepts the request and hands it to a background job (&lt;code&gt;Webhooks::WhatsappEventsJob&lt;/code&gt;, on the &lt;code&gt;low&lt;/code&gt; queue). Sidekiq is what turns that job into a conversation.&lt;/p&gt;

&lt;p&gt;So if Sidekiq isn't running, Meta sees a successful delivery, Chatwoot looks healthy, and &lt;strong&gt;no messages appear&lt;/strong&gt; — they're sitting in Redis. Before debugging Meta settings, check that Sidekiq is alive: super-admins can open &lt;code&gt;/monitoring/sidekiq&lt;/code&gt; and look for a growing &lt;code&gt;low&lt;/code&gt; queue.&lt;/p&gt;

&lt;h3&gt;
  
  
  3. Media needs persistent storage
&lt;/h3&gt;

&lt;p&gt;Photos, voice notes and documents customers send are downloaded and stored through Rails Active Storage. With the default local storage and no volume, they vanish on the next redeploy and old conversations fill with broken images. Mount a volume at &lt;code&gt;/app/storage&lt;/code&gt;, or configure S3/R2, before you go live.&lt;/p&gt;

&lt;h2&gt;
  
  
  Step-by-step: manual Cloud API setup
&lt;/h2&gt;

&lt;p&gt;This is Chatwoot's "manual flow", which works on every self-hosted install.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;1. Start the inbox in Chatwoot.&lt;/strong&gt; Go to &lt;strong&gt;Settings → Inboxes → Add Inbox → WhatsApp&lt;/strong&gt; and choose &lt;strong&gt;WhatsApp Cloud&lt;/strong&gt;. If a Quick setup screen appears, use the &lt;em&gt;manual setup flow&lt;/em&gt; link at the bottom.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;2. Prepare the Meta app.&lt;/strong&gt; In Meta for Developers, create (or open) an app, choose the use case for connecting with customers through WhatsApp, and select the business portfolio that owns the number.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;3. Copy two IDs.&lt;/strong&gt; In the app's WhatsApp &lt;strong&gt;API Setup&lt;/strong&gt; page, register your number if needed, then copy the &lt;strong&gt;Phone Number ID&lt;/strong&gt; and the &lt;strong&gt;WhatsApp Business Account ID&lt;/strong&gt;. They're different numbers — mixing them up is the most common error. Paste both into Chatwoot and continue.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;4. Create a permanent token.&lt;/strong&gt; Temporary tokens from the API Setup page expire within a day; use a system user instead:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;Meta Business Settings → &lt;strong&gt;Users → System users&lt;/strong&gt; → create an admin system user (or reuse one).&lt;/li&gt;
&lt;li&gt;Assign it your Meta app and your WhatsApp Business Account with &lt;strong&gt;full control&lt;/strong&gt;.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Generate token&lt;/strong&gt; → select the app → expiry &lt;strong&gt;Never&lt;/strong&gt; → permissions &lt;code&gt;whatsapp_business_management&lt;/code&gt; and &lt;code&gt;whatsapp_business_messaging&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;Copy it immediately (Meta shows it once) and paste it into Chatwoot as the permanent access token.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;&lt;strong&gt;5. Verify and create.&lt;/strong&gt; Chatwoot checks number access, template access, the webhook callback and the webhook subscription, and configures the webhook in Meta for you. When all four show &lt;strong&gt;Verified&lt;/strong&gt;, create the inbox and add agents.&lt;/p&gt;

&lt;p&gt;If the webhook steps fail, use &lt;strong&gt;Retry webhook setup&lt;/strong&gt;. If they keep failing, the system user probably lacks full control of the WhatsApp Business Account. As a fallback, copy the &lt;strong&gt;Webhook URL&lt;/strong&gt; and &lt;strong&gt;Verification Token&lt;/strong&gt; from Chatwoot, paste them under &lt;strong&gt;WhatsApp → Configuration&lt;/strong&gt; in your Meta app, verify, and subscribe to the &lt;code&gt;messages&lt;/code&gt; field.&lt;/p&gt;

&lt;p&gt;If template access shows as not verified, the token is missing &lt;code&gt;whatsapp_business_management&lt;/code&gt;: messages still work, templates won't sync.&lt;/p&gt;

&lt;h2&gt;
  
  
  Optional: Quick setup (embedded signup)
&lt;/h2&gt;

&lt;p&gt;Chatwoot Cloud customers get a one-click &lt;strong&gt;Connect with WhatsApp Business&lt;/strong&gt; button. Self-hosted installs can enable it too, but only after the instance admin configures their own Meta app for it. In &lt;strong&gt;Super Admin → App Config → WhatsApp Embedded&lt;/strong&gt; set:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;code&gt;WHATSAPP_APP_ID&lt;/code&gt; — your Meta app ID&lt;/li&gt;
&lt;li&gt;
&lt;code&gt;WHATSAPP_CONFIGURATION_ID&lt;/code&gt; — from Facebook Login for Business → Configurations, using the &lt;em&gt;WhatsApp Embedded Signup&lt;/em&gt; variation&lt;/li&gt;
&lt;li&gt;
&lt;code&gt;WHATSAPP_APP_SECRET&lt;/code&gt; — App Settings → Basic&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;The button stays hidden until all three are set. It's worth it if you'll onboard several numbers or clients; for one number, the manual flow is quicker.&lt;/p&gt;

&lt;h2&gt;
  
  
  Testing it
&lt;/h2&gt;

&lt;ol&gt;
&lt;li&gt;From a personal phone, message the business number.&lt;/li&gt;
&lt;li&gt;The conversation should appear in Chatwoot within seconds.&lt;/li&gt;
&lt;li&gt;Reply from Chatwoot; the message arrives on the phone.&lt;/li&gt;
&lt;li&gt;Send a photo, then redeploy the Chatwoot service and check the photo still loads.&lt;/li&gt;
&lt;/ol&gt;

&lt;p&gt;Nothing arrived? Check in this order: Sidekiq is running → &lt;code&gt;FRONTEND_URL&lt;/code&gt; matches your public domain → the Meta app's webhook is subscribed to &lt;code&gt;messages&lt;/code&gt; → the token hasn't been revoked (update it in the inbox's Configuration tab if you replaced it).&lt;/p&gt;

&lt;h2&gt;
  
  
  Running Chatwoot on Railway for this
&lt;/h2&gt;

&lt;p&gt;If you don't have a Chatwoot instance yet, I maintain a Railway template that's set up for exactly this: Chatwoot with Sidekiq supervised in the same container, Postgres with pgvector, Redis, and a volume at &lt;code&gt;/app/storage&lt;/code&gt; so WhatsApp media survives redeploys. WhatsApp, live chat and the other social channels work on the Hobby plan; email notifications need Pro.&lt;/p&gt;

&lt;p&gt;&lt;a href="https://railway.com/deploy/chatwoot-1?referralCode=Ib5Dqy&amp;amp;utm_medium=integration&amp;amp;utm_source=devto&amp;amp;utm_campaign=chatwoot-whatsapp" rel="noopener noreferrer"&gt;&lt;img src="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Frailway.com%2Fbutton.svg" alt="Deploy on Railway" width="183" height="40"&gt;&lt;/a&gt;&lt;/p&gt;

&lt;p&gt;&lt;em&gt;(Disclosure: I earn a share of Railway usage from deployments of this template. Everything above applies to any self-hosted Chatwoot.)&lt;/em&gt;&lt;/p&gt;

&lt;p&gt;For the rest of the setup — email, storage, upgrades, backups — see &lt;a href="https://dev.to/amritasha_agrawal_a297c7d/self-hosting-chatwoot-on-railway-what-actually-breaks-email-attachments-sidekiq-37fh"&gt;Self-Hosting Chatwoot on Railway: What Actually Breaks&lt;/a&gt;.&lt;/p&gt;

&lt;h2&gt;
  
  
  Checklist
&lt;/h2&gt;

&lt;ul&gt;
&lt;li&gt;[ ] &lt;code&gt;FRONTEND_URL&lt;/code&gt; is your final public HTTPS domain before creating the inbox&lt;/li&gt;
&lt;li&gt;[ ] Sidekiq running (check &lt;code&gt;/monitoring/sidekiq&lt;/code&gt;)&lt;/li&gt;
&lt;li&gt;[ ] Volume at &lt;code&gt;/app/storage&lt;/code&gt; or S3/R2 for media&lt;/li&gt;
&lt;li&gt;[ ] Number not active in the WhatsApp phone app&lt;/li&gt;
&lt;li&gt;[ ] Phone Number ID and WhatsApp Business Account ID not swapped&lt;/li&gt;
&lt;li&gt;[ ] Permanent system-user token, expiry Never, both WhatsApp permissions&lt;/li&gt;
&lt;li&gt;[ ] All four checks Verified; webhook subscribed to &lt;code&gt;messages&lt;/code&gt;
&lt;/li&gt;
&lt;li&gt;[ ] Templates approved for messaging customers after 24 hours&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;Questions or something out of date? Say so in the comments — I'll update it.&lt;/p&gt;

</description>
      <category>chatwoot</category>
      <category>whatsapp</category>
      <category>selfhosted</category>
      <category>tutorial</category>
    </item>
    <item>
      <title>Self-Hosting Listmonk on Railway: The Newsletter Server That Can't Send Email on the Wrong Plan</title>
      <dc:creator>Amritasha Agrawal</dc:creator>
      <pubDate>Fri, 06 Nov 2026 12:04:06 +0000</pubDate>
      <link>https://dev.to/amritasha_agrawal_a297c7d/self-hosting-listmonk-on-railway-the-newsletter-server-that-cant-send-email-on-the-wrong-plan-bc</link>
      <guid>https://dev.to/amritasha_agrawal_a297c7d/self-hosting-listmonk-on-railway-the-newsletter-server-that-cant-send-email-on-the-wrong-plan-bc</guid>
      <description>&lt;p&gt;Listmonk is an open-source newsletter and mailing-list manager: subscriber lists, segmentation with SQL, campaign templates, analytics, and transactional mail over an API. It's a single Go binary backed by Postgres, it idles at a few tens of megabytes of RAM, and it's free — the only per-email cost is whichever mail provider actually delivers your messages.&lt;/p&gt;

&lt;p&gt;That combination makes it one of the cheapest things you can self-host. It also means the things that go wrong are not "it crashed" but "it's running and nothing is being delivered", which is worse.&lt;/p&gt;

&lt;p&gt;This guide covers running Listmonk on Railway, a usage-billed container platform with managed Postgres and volumes. Most of it applies to any container host.&lt;/p&gt;

&lt;h2&gt;
  
  
  How Listmonk sends mail
&lt;/h2&gt;

&lt;p&gt;Listmonk doesn't deliver email itself. It renders each message and hands it to an SMTP server — Amazon SES, Postmark, SendGrid, Mailgun, Brevo, your own Postfix — through a connection pool you configure in &lt;strong&gt;Settings → SMTP&lt;/strong&gt;. You can register several SMTP servers and Listmonk spreads the load across them.&lt;/p&gt;

&lt;p&gt;It also has &lt;em&gt;messengers&lt;/em&gt;, which POST each message as JSON to a web service of your choice. Those are for SMS, push notifications and similar channels; email still goes over SMTP.&lt;/p&gt;

&lt;p&gt;That's the background for the first decision.&lt;/p&gt;

&lt;h2&gt;
  
  
  Decision 1: Your plan has to allow outbound SMTP
&lt;/h2&gt;

&lt;p&gt;&lt;strong&gt;Railway blocks outbound SMTP (ports 25, 465, 587 and 2525) on its Free, Trial and Hobby plans.&lt;/strong&gt; It's a platform-wide anti-spam policy, documented under &lt;a href="https://docs.railway.com/networking/outbound-networking" rel="noopener noreferrer"&gt;outbound networking&lt;/a&gt;, and it can't be lifted per project.&lt;/p&gt;

&lt;p&gt;For most apps that's an inconvenience — no password-reset emails. For Listmonk it's the whole product: on those plans, campaigns start, sit in "running", and every message fails to connect. Listmonk's own docs mention that some hosts block SMTP ports; Railway is one of them below the Pro plan.&lt;/p&gt;

&lt;p&gt;So:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;Production newsletters need Railway Pro&lt;/strong&gt; (or any host that allows outbound SMTP).&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Hobby is still fine for evaluation&lt;/strong&gt;: building lists, importing subscribers, designing templates, testing the API. Just don't expect a test campaign to arrive.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;Check this before you import a single subscriber.&lt;/p&gt;

&lt;h2&gt;
  
  
  Decision 2: Upgrades need &lt;code&gt;--upgrade&lt;/code&gt;, and a backup first
&lt;/h2&gt;

&lt;p&gt;Listmonk keeps its schema version in the database. A new release ships migrations, applied by running the binary with &lt;code&gt;--upgrade&lt;/code&gt;. The official Docker Compose file runs three commands in sequence on every start:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;./listmonk &lt;span class="nt"&gt;--install&lt;/span&gt; &lt;span class="nt"&gt;--idempotent&lt;/span&gt; &lt;span class="nt"&gt;--yes&lt;/span&gt;   &lt;span class="c"&gt;# create tables if this is a new DB&lt;/span&gt;
./listmonk &lt;span class="nt"&gt;--upgrade&lt;/span&gt; &lt;span class="nt"&gt;--yes&lt;/span&gt;                &lt;span class="c"&gt;# apply any pending migrations&lt;/span&gt;
./listmonk                                &lt;span class="c"&gt;# start the server&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;If your container only runs the first and last, a new image version will boot against an old schema and refuse to start until someone runs the upgrade by hand. Two more rules from Listmonk's upgrade guide:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;Back up Postgres before every upgrade.&lt;/strong&gt; Upgrades are idempotent, but downgrades are not supported: going back means restoring the pre-upgrade database.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Pin the image tag.&lt;/strong&gt; &lt;code&gt;listmonk/listmonk:latest&lt;/code&gt; means a redeploy you did for an unrelated reason can pull a new major version. Pin a release (&lt;code&gt;listmonk/listmonk:v6.2.0&lt;/code&gt; at the time of writing) and upgrade deliberately.&lt;/li&gt;
&lt;/ul&gt;

&lt;h2&gt;
  
  
  Decision 3: Where uploaded images live
&lt;/h2&gt;

&lt;p&gt;Images you upload for campaigns go through &lt;strong&gt;Settings → Media&lt;/strong&gt;. The default backend is the filesystem, under Listmonk's &lt;code&gt;uploads&lt;/code&gt; directory — inside the container. On any container platform that directory is wiped on every redeploy, and every newsletter you've already sent now has broken images in it.&lt;/p&gt;

&lt;p&gt;Two correct setups:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;A volume&lt;/strong&gt; mounted at the uploads path (&lt;code&gt;/listmonk/uploads&lt;/code&gt; in the official image), with the media settings pointing there.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;S3-compatible storage&lt;/strong&gt;, configured in the same settings page. This is the better choice once you're sending to real audiences, because images are served by the bucket rather than by your Listmonk instance — a large campaign means thousands of image requests within minutes of sending.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;Decide before your first campaign; switching later doesn't move old files.&lt;/p&gt;

&lt;h2&gt;
  
  
  Decision 4: Bounces, or your sender reputation pays
&lt;/h2&gt;

&lt;p&gt;Every provider tracks your bounce and complaint rates and throttles or suspends you if they climb. Listmonk can mark bounced addresses and stop mailing them, but only if you turn it on (&lt;strong&gt;Settings → Bounces&lt;/strong&gt;) and give it a source:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;Provider webhooks&lt;/strong&gt; — the cleanest option. Listmonk has built-in endpoints for Amazon SES, SendGrid, Postmark, Forward Email and Lettermint at &lt;code&gt;/webhooks/service/&amp;lt;provider&amp;gt;&lt;/code&gt;. Your Listmonk URL has to be publicly reachable for the provider to call it.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;A POP3 bounce mailbox&lt;/strong&gt; that Listmonk scans. Use a dedicated mailbox: Listmonk deletes the messages it processes.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;The generic bounce API&lt;/strong&gt; (&lt;code&gt;POST /webhooks/bounce&lt;/code&gt;) for anything else.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;If you only set up one thing beyond SMTP, make it this.&lt;/p&gt;

&lt;h2&gt;
  
  
  Configuration on a container platform
&lt;/h2&gt;

&lt;p&gt;Listmonk reads its config file, but every key can also come from an environment variable: &lt;code&gt;LISTMONK_&lt;/code&gt; plus the section and key, joined by a double underscore. The ones you need on Railway:&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="nv"&gt;LISTMONK_app__address&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;0.0.0.0:9000
&lt;span class="nv"&gt;LISTMONK_db__host&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&amp;lt;postgres private host&amp;gt;
&lt;span class="nv"&gt;LISTMONK_db__port&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;5432
&lt;span class="nv"&gt;LISTMONK_db__user&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&amp;lt;user&amp;gt;
&lt;span class="nv"&gt;LISTMONK_db__password&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&amp;lt;password&amp;gt;
&lt;span class="nv"&gt;LISTMONK_db__database&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&amp;lt;database&amp;gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Set them as references to the Postgres service so they follow it automatically, and keep the connection on Railway's private network.&lt;/p&gt;

&lt;p&gt;The first admin account is created on install. Set &lt;code&gt;LISTMONK_ADMIN_USER&lt;/code&gt; and &lt;code&gt;LISTMONK_ADMIN_PASSWORD&lt;/code&gt; before the first boot and that becomes the Super Admin; leave them unset and Listmonk asks you to create one in the browser — in which case, open the URL immediately, before anyone else does.&lt;/p&gt;

&lt;p&gt;Everything else — SMTP servers, media, bounces, the public root URL used in unsubscribe and tracking links — lives in &lt;strong&gt;Settings&lt;/strong&gt; and is stored in the database, so it survives redeploys without more environment variables. Set &lt;strong&gt;Settings → General → Root URL&lt;/strong&gt; to your public URL before sending anything: it's baked into every unsubscribe link.&lt;/p&gt;

&lt;h2&gt;
  
  
  Deploying it
&lt;/h2&gt;

&lt;p&gt;I maintain a Railway template with Listmonk and Railway Postgres 18 wired together over the private network, an admin account created from variables on the first boot, and a health check on &lt;code&gt;/health&lt;/code&gt;.&lt;/p&gt;

&lt;p&gt;&lt;a href="https://railway.com/deploy/listmonk-2?referralCode=Ib5Dqy&amp;amp;utm_medium=integration&amp;amp;utm_source=devto&amp;amp;utm_campaign=listmonk-guide" rel="noopener noreferrer"&gt;&lt;img src="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Frailway.com%2Fbutton.svg" alt="Deploy on Railway" width="183" height="40"&gt;&lt;/a&gt;&lt;/p&gt;

&lt;p&gt;&lt;em&gt;(Disclosure: I earn a share of Railway usage from deployments of this template. The source is public at &lt;a href="https://github.com/Amritasha/listmonk" rel="noopener noreferrer"&gt;Amritasha/listmonk&lt;/a&gt;, and everything here applies if you set it up yourself.)&lt;/em&gt;&lt;/p&gt;

&lt;p&gt;After the deploy goes green:&lt;/p&gt;

&lt;ol&gt;
&lt;li&gt;Log in with the admin user and password from the service variables, and change the password.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Settings → General&lt;/strong&gt;: set the Root URL to your public domain.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Settings → Media&lt;/strong&gt;: add a volume at the uploads path or configure S3 before uploading anything.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Settings → SMTP&lt;/strong&gt;: add your provider (on a plan that allows SMTP), then send a test to yourself.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Settings → Bounces&lt;/strong&gt;: enable it and wire your provider's webhook.&lt;/li&gt;
&lt;li&gt;Import a small list, send a real campaign to yourself and one other address, and check the unsubscribe link works.&lt;/li&gt;
&lt;/ol&gt;

&lt;h2&gt;
  
  
  Keeping it fast as lists grow
&lt;/h2&gt;

&lt;p&gt;Listmonk is quick until the subscriber, view and click tables get large. Then admin pages that count and aggregate (subscriber totals, campaign stats) start taking seconds. Two built-in fixes from the maintenance docs:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;Settings → Performance → Cache slow database queries&lt;/strong&gt; — recommended once those pages stop loading instantly.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;&lt;code&gt;VACUUM ANALYZE&lt;/code&gt; weekly&lt;/strong&gt; on the Postgres database. It's briefly blocking on a big database, so schedule it outside sending windows.&lt;/li&gt;
&lt;/ul&gt;

&lt;h2&gt;
  
  
  Backups
&lt;/h2&gt;

&lt;p&gt;Everything — subscribers, consent records, campaigns, settings — is in Postgres:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;Railway volume backups.&lt;/strong&gt; The Postgres volume's Backups tab offers daily (kept 6 days), weekly (kept 27 days) and monthly (kept 89 days) schedules. Turn them on.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;An off-platform copy&lt;/strong&gt;, because Railway backups restore only inside the same project:
&lt;/li&gt;
&lt;/ul&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;  pg_dump &lt;span class="s2"&gt;"&lt;/span&gt;&lt;span class="nv"&gt;$DATABASE_PUBLIC_URL&lt;/span&gt;&lt;span class="s2"&gt;"&lt;/span&gt; &lt;span class="nt"&gt;-Fc&lt;/span&gt; &lt;span class="nt"&gt;-f&lt;/span&gt; listmonk-&lt;span class="si"&gt;$(&lt;/span&gt;&lt;span class="nb"&gt;date&lt;/span&gt; +%F&lt;span class="si"&gt;)&lt;/span&gt;.dump
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;Always a fresh dump right before an upgrade&lt;/strong&gt; — it's the only downgrade path.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;Your subscriber list is personal data. Treat the dumps accordingly: encrypted storage, limited access, and a retention period.&lt;/p&gt;

&lt;h2&gt;
  
  
  What it costs
&lt;/h2&gt;

&lt;p&gt;Railway bills per second: about $10 per GB of RAM per month, $20 per vCPU per month, and $0.16 per GB-month of volume storage. Hobby is $5/month including $5 of usage; Pro is $20/month including $20.&lt;/p&gt;

&lt;p&gt;Listmonk itself is tiny at idle; Postgres is usually the bigger of the two. Sending a large campaign briefly uses more CPU, and images served from the instance add egress, which is another reason to put media in a bucket. Delivery costs are separate and charged by your mail provider. After a week, each service's Metrics tab shows the real numbers.&lt;/p&gt;

&lt;h2&gt;
  
  
  When not to self-host it
&lt;/h2&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;You don't want to own deliverability.&lt;/strong&gt; SPF, DKIM, DMARC, bounce handling and complaint rates are your job now. Hosted newsletter tools do that for you.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;You won't run a Pro-level plan or an SMTP-friendly host.&lt;/strong&gt; Without outbound SMTP, Listmonk can't send.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Your list is small and your time isn't.&lt;/strong&gt; Free tiers of hosted tools may cover you.&lt;/li&gt;
&lt;/ul&gt;

&lt;h2&gt;
  
  
  Checklist
&lt;/h2&gt;

&lt;ul&gt;
&lt;li&gt;[ ] Plan allows outbound SMTP (Railway Pro or higher)&lt;/li&gt;
&lt;li&gt;[ ] Image pinned; start command runs &lt;code&gt;--install --idempotent&lt;/code&gt; &lt;strong&gt;and&lt;/strong&gt; &lt;code&gt;--upgrade&lt;/code&gt;
&lt;/li&gt;
&lt;li&gt;[ ] Root URL set before the first campaign&lt;/li&gt;
&lt;li&gt;[ ] Media on a volume or S3&lt;/li&gt;
&lt;li&gt;[ ] SMTP provider configured and test email received&lt;/li&gt;
&lt;li&gt;[ ] Bounce processing enabled with a provider webhook or dedicated POP3 mailbox&lt;/li&gt;
&lt;li&gt;[ ] SPF, DKIM and DMARC set up for your sending domain&lt;/li&gt;
&lt;li&gt;[ ] Volume backups + off-platform &lt;code&gt;pg_dump&lt;/code&gt;; fresh dump before each upgrade&lt;/li&gt;
&lt;li&gt;[ ] "Cache slow database queries" + weekly &lt;code&gt;VACUUM ANALYZE&lt;/code&gt; once lists get big&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;If something here is wrong or out of date, say so in the comments — I'll fix it.&lt;/p&gt;

</description>
      <category>selfhosted</category>
      <category>email</category>
      <category>newsletter</category>
      <category>postgres</category>
    </item>
    <item>
      <title>Self-Hosting Metabase on Railway: The App Database, JVM Memory and the Encryption Key You Can't Add Later</title>
      <dc:creator>Amritasha Agrawal</dc:creator>
      <pubDate>Fri, 06 Nov 2026 11:51:06 +0000</pubDate>
      <link>https://dev.to/amritasha_agrawal_a297c7d/self-hosting-metabase-on-railway-the-app-database-jvm-memory-and-the-encryption-key-you-cant-add-2d4b</link>
      <guid>https://dev.to/amritasha_agrawal_a297c7d/self-hosting-metabase-on-railway-the-app-database-jvm-memory-and-the-encryption-key-you-cant-add-2d4b</guid>
      <description>&lt;p&gt;Metabase is the open-source BI tool people install when they want dashboards over their own database without writing a frontend. The open-source edition is free to self-host, and it's a single Java process — which makes it look like the easiest thing on your list to deploy.&lt;/p&gt;

&lt;p&gt;It mostly is. But four decisions get made for you by default, and each one is painful to change after your team has built dashboards on it: where Metabase stores its own data, how much memory the JVM may use, whether connection credentials are encrypted, and how upgrades happen.&lt;/p&gt;

&lt;p&gt;This guide runs Metabase on Railway, a usage-billed container platform with managed Postgres and private networking, so there's no VM to look after. Most of it applies to any container host.&lt;/p&gt;

&lt;h2&gt;
  
  
  Two databases, not one
&lt;/h2&gt;

&lt;p&gt;Metabase talks to two kinds of database, and it's worth keeping them separate in your head:&lt;/p&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;&lt;/th&gt;
&lt;th&gt;What it is&lt;/th&gt;
&lt;th&gt;What's in it&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;&lt;strong&gt;Application database&lt;/strong&gt;&lt;/td&gt;
&lt;td&gt;Metabase's own storage&lt;/td&gt;
&lt;td&gt;Every question, dashboard, collection, user, permission, and the connection details for your data sources&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;strong&gt;Data sources&lt;/strong&gt;&lt;/td&gt;
&lt;td&gt;The databases you analyse&lt;/td&gt;
&lt;td&gt;Your actual data — Metabase only reads it (unless you enable writes)&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;p&gt;Losing a data source connection is an inconvenience. Losing the application database is losing every dashboard anyone ever built.&lt;/p&gt;

&lt;h2&gt;
  
  
  Decision 1: Don't run on H2
&lt;/h2&gt;

&lt;p&gt;If you start the Metabase image with no configuration, it stores the application database in an embedded H2 file inside the container. Metabase's own docs say not to run production on H2, and on a container platform it's worse than "not recommended": the container filesystem is replaced on every redeploy, so an H2 file that isn't on a volume disappears with your dashboards in it.&lt;/p&gt;

&lt;p&gt;Point Metabase at Postgres from the first boot:&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="nv"&gt;MB_DB_TYPE&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;postgres
&lt;span class="nv"&gt;MB_DB_HOST&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&amp;lt;postgres host&amp;gt;
&lt;span class="nv"&gt;MB_DB_PORT&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;5432
&lt;span class="nv"&gt;MB_DB_DBNAME&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&amp;lt;database&amp;gt;
&lt;span class="nv"&gt;MB_DB_USER&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&amp;lt;user&amp;gt;
&lt;span class="nv"&gt;MB_DB_PASS&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&amp;lt;password&amp;gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;On Railway, set these as reference variables pointing at the Postgres service, so they track the database automatically and stay on the private network.&lt;/p&gt;

&lt;p&gt;If you already have dashboards on H2, Metabase has a &lt;code&gt;load-from-h2&lt;/code&gt; migration command — run it once, before you have two diverging copies.&lt;/p&gt;

&lt;h2&gt;
  
  
  Decision 2: Set the encryption key on day one
&lt;/h2&gt;

&lt;p&gt;&lt;code&gt;MB_ENCRYPTION_SECRET_KEY&lt;/code&gt; makes Metabase encrypt the connection details it stores for your data sources — hostnames, usernames and &lt;strong&gt;passwords for your production databases&lt;/strong&gt;. Without it, those sit in the application database in plaintext.&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="c"&gt;# at least 16 characters; Metabase's docs generate one like this:&lt;/span&gt;
openssl rand &lt;span class="nt"&gt;-base64&lt;/span&gt; 32
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The catch is timing. On a fresh Metabase, setting the key is all you need. On a Metabase that already has data sources, Metabase &lt;strong&gt;won't start&lt;/strong&gt; with the key set until you've run the one-off &lt;code&gt;enable-encryption&lt;/code&gt; CLI command against the application database. And if you ever lose or change the key, every encrypted connection has to be re-entered by hand in the admin panel (there's a &lt;code&gt;rotate-encryption-key&lt;/code&gt; command for planned rotation).&lt;/p&gt;

&lt;p&gt;So: generate it before the first boot, put it in your secret store, and never edit it casually.&lt;/p&gt;

&lt;h2&gt;
  
  
  Decision 3: Tell the JVM how much memory it gets
&lt;/h2&gt;

&lt;p&gt;Metabase runs on the JVM. A container-aware JVM sizes its maximum heap from the container's memory limit — by default a quarter of it. On a platform where the limit is a generous plan ceiling rather than what you intend to pay for, that default is arbitrary: it can be too small for a busy instance, and it's not a deliberate cost ceiling either.&lt;/p&gt;

&lt;p&gt;The Metabase image appends whatever you put in &lt;code&gt;JAVA_OPTS&lt;/code&gt;, so set the heap explicitly:&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="nv"&gt;JAVA_OPTS&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="nt"&gt;-Xmx2g&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Two things to know about out-of-memory behaviour: the official image starts Java with &lt;code&gt;-XX:+CrashOnOutOfMemoryError&lt;/code&gt;, so a heap overflow kills the process rather than leaving it half-alive, and your platform's restart policy decides what happens next. If that policy gives up after a few retries, Metabase stays down — worth knowing before the first big dashboard query hits it.&lt;/p&gt;

&lt;h2&gt;
  
  
  Decision 4: Pin the version, back up before upgrading
&lt;/h2&gt;

&lt;p&gt;Metabase migrates its application database on startup when you move to a newer version. Their upgrade guide is blunt about two things:&lt;/p&gt;

&lt;ol&gt;
&lt;li&gt;
&lt;strong&gt;Back up the application database before every upgrade.&lt;/strong&gt; Downgrading after a major upgrade means restoring that backup (or running a &lt;code&gt;migrate down&lt;/code&gt; command from the newer version's JAR).&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Don't let the orchestrator kill Metabase mid-migration&lt;/strong&gt;, or you can end up with a corrupted application database.&lt;/li&gt;
&lt;/ol&gt;

&lt;p&gt;On a container platform that translates to:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;Pin an exact image tag (&lt;code&gt;metabase/metabase:v0.xx.y&lt;/code&gt;), never &lt;code&gt;latest&lt;/code&gt;, so an unrelated redeploy can't upgrade you.&lt;/li&gt;
&lt;li&gt;Give the health check (&lt;code&gt;/api/health&lt;/code&gt;) a long timeout — the template below uses 600 seconds — so a slow migration isn't mistaken for a crash.&lt;/li&gt;
&lt;li&gt;Take a backup, then bump the tag, then watch the logs until migrations finish.&lt;/li&gt;
&lt;/ul&gt;

&lt;h2&gt;
  
  
  Connecting your data
&lt;/h2&gt;

&lt;p&gt;Metabase's own recommendation is a dedicated database user with &lt;strong&gt;read-only&lt;/strong&gt; access to the schemas you want to analyse. It's the cheapest safety net you'll ever set up: a dashboard can't drop a table if the account can't write.&lt;/p&gt;

&lt;p&gt;Two more things that affect the database you connect:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;Sync and scans run on their own.&lt;/strong&gt; By default Metabase does a lightweight hourly schema sync and a heavier daily scan of field values. On a large production database, move them to off-peak hours in the database's admin settings.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Point it at a replica if you have one.&lt;/strong&gt; Analytical queries and transactional traffic compete for the same resources.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;If the data source is another Railway service in the same project, connect over the private network (&lt;code&gt;&amp;lt;service&amp;gt;.railway.internal&lt;/code&gt;) rather than the public TCP proxy — it's faster and avoids egress charges.&lt;/p&gt;

&lt;h2&gt;
  
  
  Email and alerts on Railway
&lt;/h2&gt;

&lt;p&gt;Dashboard subscriptions and alerts can go to email or Slack. Email uses SMTP, and &lt;strong&gt;Railway blocks outbound SMTP on the Free, Trial and Hobby plans&lt;/strong&gt; — so on those plans email subscriptions won't be delivered. Slack subscriptions go over Slack's HTTPS API and aren't affected; set up the Slack app under Admin → Settings → Slack.&lt;/p&gt;

&lt;p&gt;Also set &lt;code&gt;MB_SITE_URL&lt;/code&gt; to your public URL, so links in subscriptions and alerts point somewhere real.&lt;/p&gt;

&lt;h2&gt;
  
  
  Deploying it
&lt;/h2&gt;

&lt;p&gt;I maintain a Railway template that sets up the application-database side for you: a pinned Metabase image (bump the tag in the Dockerfile to upgrade), Railway Postgres 18 as the application database wired in with reference variables, and a 600-second health-check timeout for first-boot and upgrade migrations.&lt;/p&gt;

&lt;p&gt;&lt;a href="https://railway.com/deploy/metabase-updated-jun26?referralCode=Ib5Dqy&amp;amp;utm_medium=integration&amp;amp;utm_source=devto&amp;amp;utm_campaign=metabase-guide" rel="noopener noreferrer"&gt;&lt;img src="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Frailway.com%2Fbutton.svg" alt="Deploy on Railway" width="183" height="40"&gt;&lt;/a&gt;&lt;/p&gt;

&lt;p&gt;&lt;em&gt;(Disclosure: I earn a share of Railway usage from deployments of this template. The source is public at &lt;a href="https://github.com/Amritasha/metabase-railway" rel="noopener noreferrer"&gt;Amritasha/metabase-railway&lt;/a&gt;, and everything above applies if you set it up yourself.)&lt;/em&gt;&lt;/p&gt;

&lt;p&gt;After the deploy goes green:&lt;/p&gt;

&lt;ol&gt;
&lt;li&gt;
&lt;strong&gt;Before opening the URL&lt;/strong&gt;, add &lt;code&gt;MB_ENCRYPTION_SECRET_KEY&lt;/code&gt; and &lt;code&gt;JAVA_OPTS&lt;/code&gt; to the Metabase service and redeploy. Doing it now avoids the &lt;code&gt;enable-encryption&lt;/code&gt; step later.&lt;/li&gt;
&lt;li&gt;Open the public URL and complete the setup wizard — it creates the admin account. Do this straight away; until it's done, anyone with the URL can claim the instance.&lt;/li&gt;
&lt;li&gt;Set &lt;code&gt;MB_SITE_URL&lt;/code&gt; to the public URL.&lt;/li&gt;
&lt;li&gt;Create a read-only database user and add your data source with it.&lt;/li&gt;
&lt;/ol&gt;

&lt;h2&gt;
  
  
  Backups
&lt;/h2&gt;

&lt;p&gt;The only stateful thing is the application database:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;Railway volume backups.&lt;/strong&gt; The Postgres service's volume has a Backups tab with daily (kept 6 days), weekly (kept 27 days) and monthly (kept 89 days) schedules. Turn it on.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;One copy off-platform.&lt;/strong&gt; Railway backups restore only within the same project and environment. A periodic &lt;code&gt;pg_dump&lt;/code&gt; covers the rest:
&lt;/li&gt;
&lt;/ul&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;  pg_dump &lt;span class="s2"&gt;"&lt;/span&gt;&lt;span class="nv"&gt;$DATABASE_PUBLIC_URL&lt;/span&gt;&lt;span class="s2"&gt;"&lt;/span&gt; &lt;span class="nt"&gt;-Fc&lt;/span&gt; &lt;span class="nt"&gt;-f&lt;/span&gt; metabase-&lt;span class="si"&gt;$(&lt;/span&gt;&lt;span class="nb"&gt;date&lt;/span&gt; +%F&lt;span class="si"&gt;)&lt;/span&gt;.dump
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;(Use a client at least as new as the server — 18 for the template.)&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;Back up your encryption key separately.&lt;/strong&gt; A restored database is useless if its connection details are encrypted with a key you no longer have.&lt;/li&gt;
&lt;/ul&gt;

&lt;h2&gt;
  
  
  What it costs
&lt;/h2&gt;

&lt;p&gt;Railway bills per second: about $10 per GB of RAM per month, $20 per vCPU per month, and $0.16 per GB-month of volume storage. Hobby is $5/month including $5 of usage; Pro is $20/month including $20.&lt;/p&gt;

&lt;p&gt;Metabase is a long-running JVM, so it holds its memory whether or not anyone is looking at a dashboard, and its RAM is most of the bill; the Postgres application database is small. Your &lt;code&gt;-Xmx&lt;/code&gt; sets the ceiling for the heap, and the JVM uses some memory beyond it. After a week, the Metabase service's Metrics tab shows what your team's usage actually costs.&lt;/p&gt;

&lt;h2&gt;
  
  
  When not to self-host it
&lt;/h2&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;You need SAML/JWT single sign-on, row-level data permissions or official support.&lt;/strong&gt; Those are in Metabase's paid editions.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Nobody will own upgrades.&lt;/strong&gt; A self-hosted BI tool that's never upgraded accumulates security fixes it doesn't have.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Your data lives somewhere Metabase can't reach privately.&lt;/strong&gt; Exposing a production database to the public internet so a dashboard can read it is a worse trade than paying for hosting near the data.&lt;/li&gt;
&lt;/ul&gt;

&lt;h2&gt;
  
  
  Checklist
&lt;/h2&gt;

&lt;ul&gt;
&lt;li&gt;[ ] Application database is Postgres, not H2&lt;/li&gt;
&lt;li&gt;[ ] &lt;code&gt;MB_ENCRYPTION_SECRET_KEY&lt;/code&gt; set before the first data source, and stored safely&lt;/li&gt;
&lt;li&gt;[ ] &lt;code&gt;JAVA_OPTS=-Xmx...&lt;/code&gt; set deliberately&lt;/li&gt;
&lt;li&gt;[ ] Image pinned to an exact version; long health-check timeout&lt;/li&gt;
&lt;li&gt;[ ] Setup wizard completed right after deploy&lt;/li&gt;
&lt;li&gt;[ ] &lt;code&gt;MB_SITE_URL&lt;/code&gt; set&lt;/li&gt;
&lt;li&gt;[ ] Read-only database user for each data source&lt;/li&gt;
&lt;li&gt;[ ] Sync/scan schedule moved off-peak for large databases&lt;/li&gt;
&lt;li&gt;[ ] Email on a plan with SMTP, or Slack for subscriptions&lt;/li&gt;
&lt;li&gt;[ ] Volume backups + off-platform &lt;code&gt;pg_dump&lt;/code&gt;; encryption key backed up separately&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;If something here is wrong or out of date, say so in the comments — I'll fix it.&lt;/p&gt;

</description>
      <category>selfhosted</category>
      <category>analytics</category>
      <category>postgres</category>
      <category>devops</category>
    </item>
    <item>
      <title>Self-Hosting Langfuse v4 on Railway: ClickHouse, S3 and the Things That Fail Silently</title>
      <dc:creator>Amritasha Agrawal</dc:creator>
      <pubDate>Fri, 06 Nov 2026 10:26:31 +0000</pubDate>
      <link>https://dev.to/amritasha_agrawal_a297c7d/self-hosting-langfuse-v4-on-railway-clickhouse-s3-and-the-things-that-fail-silently-4jd9</link>
      <guid>https://dev.to/amritasha_agrawal_a297c7d/self-hosting-langfuse-v4-on-railway-clickhouse-s3-and-the-things-that-fail-silently-4jd9</guid>
      <description>&lt;p&gt;Langfuse is an open-source LLM engineering platform: tracing for every LLM call, tool call and agent step, plus prompt management, evals and cost tracking. The core is MIT-licensed and self-hostable, which is the main reason people pick it — prompts and model outputs often contain exactly the data you don't want in a third-party SaaS.&lt;/p&gt;

&lt;p&gt;Langfuse v4 changed the data model: everything is now an observation in a wide, mostly immutable ClickHouse table (&lt;code&gt;events_full&lt;/code&gt;, with a lighter &lt;code&gt;events_core&lt;/code&gt; projection for tables and charts). It's faster, and it raised the infrastructure bar — most v3-era Docker Compose files and templates won't run it unchanged.&lt;/p&gt;

&lt;p&gt;This guide covers running v4 on Railway, a usage-billed container platform with managed volumes, private networking and S3-compatible buckets, so there's no VM to look after. Most of it applies to any single-node setup.&lt;/p&gt;

&lt;h2&gt;
  
  
  The six parts
&lt;/h2&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Component&lt;/th&gt;
&lt;th&gt;Job&lt;/th&gt;
&lt;th&gt;v4 minimum&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;&lt;strong&gt;langfuse-web&lt;/strong&gt;&lt;/td&gt;
&lt;td&gt;UI and ingestion API (public)&lt;/td&gt;
&lt;td&gt;—&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;strong&gt;langfuse-worker&lt;/strong&gt;&lt;/td&gt;
&lt;td&gt;Processes queued events into ClickHouse, runs evals and exports&lt;/td&gt;
&lt;td&gt;—&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;strong&gt;PostgreSQL&lt;/strong&gt;&lt;/td&gt;
&lt;td&gt;Users, projects, prompts, API keys, config&lt;/td&gt;
&lt;td&gt;15 (16+ recommended)&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;strong&gt;ClickHouse&lt;/strong&gt;&lt;/td&gt;
&lt;td&gt;All traces/observations/scores&lt;/td&gt;
&lt;td&gt;&lt;strong&gt;25.12&lt;/strong&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;strong&gt;Redis / Valkey&lt;/strong&gt;&lt;/td&gt;
&lt;td&gt;Queues and cache&lt;/td&gt;
&lt;td&gt;7.0&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;strong&gt;S3-compatible storage&lt;/strong&gt;&lt;/td&gt;
&lt;td&gt;Raw event payloads, media, batch exports&lt;/td&gt;
&lt;td&gt;&lt;strong&gt;required&lt;/strong&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;p&gt;Ingestion is asynchronous: the web container writes the raw event to S3, puts a pointer on a Redis queue, and the worker reads it back and inserts into ClickHouse. That's why three different components can each make "my trace never appeared" happen without any request returning an error.&lt;/p&gt;

&lt;p&gt;Langfuse's own &lt;a href="https://langfuse.com/self-hosting/configuration/scaling" rel="noopener noreferrer"&gt;scaling page&lt;/a&gt; lists production minimums of 2 CPU / 4 GiB for each container and Postgres, 1 CPU / 1.5 GiB for Redis, and 2 CPU / 8 GiB for ClickHouse. On Railway those are limits, not reservations — you're billed for what's actually used — but they tell you where the memory goes.&lt;/p&gt;

&lt;h2&gt;
  
  
  What breaks on a single node
&lt;/h2&gt;

&lt;h3&gt;
  
  
  1. ClickHouse assumes a cluster
&lt;/h3&gt;

&lt;p&gt;&lt;code&gt;CLICKHOUSE_CLUSTER_ENABLED&lt;/code&gt; defaults to &lt;code&gt;true&lt;/code&gt;, which makes the migrations run &lt;code&gt;ON CLUSTER&lt;/code&gt; statements. A single ClickHouse server with no cluster config rejects them, the web container never finishes migrating, and the health check eventually kills it. Set:&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="nv"&gt;CLICKHOUSE_CLUSTER_ENABLED&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="nb"&gt;false&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;on &lt;strong&gt;both&lt;/strong&gt; web and worker.&lt;/p&gt;

&lt;h3&gt;
  
  
  2. ClickHouse doesn't listen on IPv6
&lt;/h3&gt;

&lt;p&gt;The stock &lt;code&gt;clickhouse/clickhouse-server&lt;/code&gt; image listens on &lt;code&gt;0.0.0.0&lt;/code&gt; only. Railway's private network (&lt;code&gt;*.railway.internal&lt;/code&gt;) has historically been IPv6-only, and on such an environment web and worker get connection refused even though both services are "up". Add a config drop-in to the ClickHouse image:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight xml"&gt;&lt;code&gt;&lt;span class="c"&gt;&amp;lt;!-- /etc/clickhouse-server/config.d/railway-listen.xml --&amp;gt;&lt;/span&gt;
&lt;span class="nt"&gt;&amp;lt;clickhouse&amp;gt;&lt;/span&gt;
    &lt;span class="nt"&gt;&amp;lt;listen_host&amp;gt;&lt;/span&gt;::&lt;span class="nt"&gt;&amp;lt;/listen_host&amp;gt;&lt;/span&gt;
    &lt;span class="nt"&gt;&amp;lt;listen_host&amp;gt;&lt;/span&gt;0.0.0.0&lt;span class="nt"&gt;&amp;lt;/listen_host&amp;gt;&lt;/span&gt;
    &lt;span class="nt"&gt;&amp;lt;listen_try&amp;gt;&lt;/span&gt;1&lt;span class="nt"&gt;&amp;lt;/listen_try&amp;gt;&lt;/span&gt;
&lt;span class="nt"&gt;&amp;lt;/clickhouse&amp;gt;&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Binding both covers IPv4 and IPv6 environments; &lt;code&gt;listen_try&lt;/code&gt; stops ClickHouse from refusing to start on a host where one address family is missing.&lt;/p&gt;

&lt;h3&gt;
  
  
  3. ClickHouse 25.12 or newer
&lt;/h3&gt;

&lt;p&gt;v4 needs ClickHouse 25.12 for lightweight updates, the JSON type and full-text search. Templates and compose files written for v3 often pin 24.x; v4's migrations fail on it. Pin a current LTS (26.3 at the time of writing) rather than &lt;code&gt;latest&lt;/code&gt;, so a redeploy can't jump a major version under you.&lt;/p&gt;

&lt;h3&gt;
  
  
  4. S3 is not optional
&lt;/h3&gt;

&lt;p&gt;Langfuse's docs mark &lt;code&gt;LANGFUSE_S3_EVENT_UPLOAD_BUCKET&lt;/code&gt; as required — raw events go there before the worker processes them. You need three sets of variables (event upload, media upload, batch export), which can all point at one bucket with different prefixes:&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="nv"&gt;LANGFUSE_S3_EVENT_UPLOAD_BUCKET&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&amp;lt;bucket&amp;gt;
&lt;span class="nv"&gt;LANGFUSE_S3_EVENT_UPLOAD_PREFIX&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;events/
&lt;span class="nv"&gt;LANGFUSE_S3_MEDIA_UPLOAD_BUCKET&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&amp;lt;bucket&amp;gt;
&lt;span class="nv"&gt;LANGFUSE_S3_MEDIA_UPLOAD_PREFIX&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;media/
&lt;span class="nv"&gt;LANGFUSE_S3_BATCH_EXPORT_ENABLED&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="nb"&gt;true
&lt;/span&gt;&lt;span class="nv"&gt;LANGFUSE_S3_BATCH_EXPORT_BUCKET&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&amp;lt;bucket&amp;gt;
&lt;span class="nv"&gt;LANGFUSE_S3_BATCH_EXPORT_PREFIX&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;exports/
&lt;span class="c"&gt;# plus _REGION, _ENDPOINT, _ACCESS_KEY_ID, _SECRET_ACCESS_KEY and&lt;/span&gt;
&lt;span class="c"&gt;# _FORCE_PATH_STYLE=true for each of the three&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Prefixes must end in &lt;code&gt;/&lt;/code&gt;. One subtlety: the &lt;strong&gt;media&lt;/strong&gt; endpoint must be reachable from browsers and SDKs, not just from the server, because Langfuse hands out presigned URLs for uploads and downloads. An internal-only MinIO breaks image/audio attachments while text traces keep working. A Railway storage bucket is S3-compatible with a public endpoint, so it avoids running MinIO as a seventh service.&lt;/p&gt;

&lt;h3&gt;
  
  
  5. Node's default heap is smaller than your container
&lt;/h3&gt;

&lt;p&gt;Node.js caps its heap at about 1.7 GiB by default, regardless of how much memory the container may use. Under load the web or worker process dies with an out-of-memory error long before it hits the platform limit. Set it explicitly on both:&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="nv"&gt;NODE_OPTIONS&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="nt"&gt;--max-old-space-size&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;3072
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;h3&gt;
  
  
  6. First boot is slow
&lt;/h3&gt;

&lt;p&gt;On a fresh install, langfuse-web runs the Postgres and ClickHouse migrations before it answers HTTP. That takes minutes, not seconds. Give the web service's health check (&lt;code&gt;/api/public/health&lt;/code&gt;) a long timeout — 600 seconds is safe — or the platform restarts it mid-migration.&lt;/p&gt;

&lt;h3&gt;
  
  
  7. Old SDKs and "where are my traces?"
&lt;/h3&gt;

&lt;p&gt;This one isn't infrastructure, but it's the easiest one to hit after a v4 deploy. v4's default ingestion mode rejects &lt;strong&gt;Python SDK v2 and older&lt;/strong&gt; and &lt;strong&gt;JS/TS SDK v3 and older&lt;/strong&gt;. Use Python SDK v4+ or JS/TS SDK v5+, or plain OpenTelemetry.&lt;/p&gt;

&lt;p&gt;And within those: below &lt;strong&gt;Python SDK 4.7.0&lt;/strong&gt; or &lt;strong&gt;JS/TS SDK 5.4.0&lt;/strong&gt;, traces still arrive but can show up with a delay of around 15 minutes. If your dashboard is empty right after sending a test trace, check your SDK version before you start debugging ClickHouse.&lt;/p&gt;

&lt;h3&gt;
  
  
  8. Email is optional — but SMTP is blocked on Railway Hobby
&lt;/h3&gt;

&lt;p&gt;Langfuse only needs email for invites and password resets, and works fine without it. If you want it: Railway blocks outbound SMTP ports on the Free, Trial and Hobby plans. Langfuse has a way around that which doesn't involve SMTP at all — it can send through the AWS SES v2 API over HTTPS:&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="nv"&gt;SMTP_CONNECTION_URL&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;ses://us-east-1
&lt;span class="nv"&gt;EMAIL_FROM_ADDRESS&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;no-reply@yourdomain.com
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;(with AWS credentials in the environment and a verified sender identity). Regular &lt;code&gt;smtp://&lt;/code&gt; URLs work on Railway's Pro plan.&lt;/p&gt;

&lt;h2&gt;
  
  
  Deploying it
&lt;/h2&gt;

&lt;p&gt;I maintain a Railway template with all of the above already set: web and worker on the unmodified &lt;code&gt;langfuse/langfuse:4&lt;/code&gt; and &lt;code&gt;langfuse/langfuse-worker:4&lt;/code&gt; images, ClickHouse 26.3 with the IPv6 drop-in and a volume, Postgres 18, Redis 8.2 with a volume, and a Railway bucket wired into all three S3 configurations. &lt;code&gt;SALT&lt;/code&gt;, &lt;code&gt;ENCRYPTION_KEY&lt;/code&gt; and &lt;code&gt;NEXTAUTH_SECRET&lt;/code&gt; are generated at deploy time.&lt;/p&gt;

&lt;p&gt;&lt;a href="https://railway.com/deploy/langfuse-v4-llm-observability?referralCode=Ib5Dqy&amp;amp;utm_medium=integration&amp;amp;utm_source=devto&amp;amp;utm_campaign=langfuse-guide" rel="noopener noreferrer"&gt;&lt;img src="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Frailway.com%2Fbutton.svg" alt="Deploy on Railway" width="183" height="40"&gt;&lt;/a&gt;&lt;/p&gt;

&lt;p&gt;&lt;em&gt;(Disclosure: I earn a share of Railway usage from deployments of this template. The source is public at &lt;a href="https://github.com/Amritasha/langfuse-railway" rel="noopener noreferrer"&gt;Amritasha/langfuse-railway&lt;/a&gt;, and everything above works the same if you wire it up yourself.)&lt;/em&gt;&lt;/p&gt;

&lt;p&gt;After the deploy goes green:&lt;/p&gt;

&lt;ol&gt;
&lt;li&gt;Open the web service's public URL and sign up, then create an organisation and project. Anyone who finds the URL can also sign up until you set &lt;code&gt;AUTH_DISABLE_SIGNUP=true&lt;/code&gt; on the web service — do that once your own account (and any teammates') exist.&lt;/li&gt;
&lt;li&gt;In &lt;strong&gt;Project settings → API keys&lt;/strong&gt;, create a key pair.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Verify UTC.&lt;/strong&gt; Langfuse requires Postgres and ClickHouse to run in UTC. Both images default to it, but check once: &lt;code&gt;SHOW timezone;&lt;/code&gt; in Postgres and &lt;code&gt;SELECT timezone();&lt;/code&gt; in ClickHouse.&lt;/li&gt;
&lt;li&gt;Send a test trace:
&lt;/li&gt;
&lt;/ol&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;pip &lt;span class="nb"&gt;install&lt;/span&gt; &lt;span class="s2"&gt;"langfuse&amp;gt;=4.7"&lt;/span&gt;
&lt;span class="nb"&gt;export &lt;/span&gt;&lt;span class="nv"&gt;LANGFUSE_PUBLIC_KEY&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;pk-lf-...
&lt;span class="nb"&gt;export &lt;/span&gt;&lt;span class="nv"&gt;LANGFUSE_SECRET_KEY&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;sk-lf-...
&lt;span class="nb"&gt;export &lt;/span&gt;&lt;span class="nv"&gt;LANGFUSE_BASE_URL&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;https://&amp;lt;your-langfuse-domain&amp;gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;





&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight python"&gt;&lt;code&gt;&lt;span class="kn"&gt;from&lt;/span&gt; &lt;span class="n"&gt;langfuse&lt;/span&gt; &lt;span class="kn"&gt;import&lt;/span&gt; &lt;span class="n"&gt;get_client&lt;/span&gt;

&lt;span class="n"&gt;langfuse&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nf"&gt;get_client&lt;/span&gt;&lt;span class="p"&gt;()&lt;/span&gt;

&lt;span class="k"&gt;with&lt;/span&gt; &lt;span class="n"&gt;langfuse&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;start_as_current_observation&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;as_type&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="sh"&gt;"&lt;/span&gt;&lt;span class="s"&gt;span&lt;/span&gt;&lt;span class="sh"&gt;"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;name&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="sh"&gt;"&lt;/span&gt;&lt;span class="s"&gt;smoke-test&lt;/span&gt;&lt;span class="sh"&gt;"&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="k"&gt;as&lt;/span&gt; &lt;span class="n"&gt;span&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
    &lt;span class="k"&gt;with&lt;/span&gt; &lt;span class="n"&gt;langfuse&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;start_as_current_observation&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;
        &lt;span class="n"&gt;as_type&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="sh"&gt;"&lt;/span&gt;&lt;span class="s"&gt;generation&lt;/span&gt;&lt;span class="sh"&gt;"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;name&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="sh"&gt;"&lt;/span&gt;&lt;span class="s"&gt;fake-llm-call&lt;/span&gt;&lt;span class="sh"&gt;"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;model&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="sh"&gt;"&lt;/span&gt;&lt;span class="s"&gt;gpt-4o&lt;/span&gt;&lt;span class="sh"&gt;"&lt;/span&gt;
    &lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="k"&gt;as&lt;/span&gt; &lt;span class="n"&gt;gen&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
        &lt;span class="n"&gt;gen&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;update&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nb"&gt;input&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="sh"&gt;"&lt;/span&gt;&lt;span class="s"&gt;ping&lt;/span&gt;&lt;span class="sh"&gt;"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;output&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="sh"&gt;"&lt;/span&gt;&lt;span class="s"&gt;pong&lt;/span&gt;&lt;span class="sh"&gt;"&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
    &lt;span class="n"&gt;span&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;update&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;output&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="sh"&gt;"&lt;/span&gt;&lt;span class="s"&gt;ok&lt;/span&gt;&lt;span class="sh"&gt;"&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;

&lt;span class="n"&gt;langfuse&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;flush&lt;/span&gt;&lt;span class="p"&gt;()&lt;/span&gt;  &lt;span class="c1"&gt;# short-lived scripts must flush before exiting
&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;It should show up in the Observations view within seconds. If it doesn't: check the worker's logs first (queue processing errors land there), then the SDK version, then the S3 variables.&lt;/p&gt;

&lt;h2&gt;
  
  
  Disk: the thing that will eventually page you
&lt;/h2&gt;

&lt;p&gt;Observability data grows with traffic, and nearly all of it lands on the ClickHouse volume. When ClickHouse runs out of space, inserts fail with &lt;code&gt;NOT_ENOUGH_SPACE&lt;/code&gt; and ingestion stops.&lt;/p&gt;

&lt;p&gt;Check what's using the space:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight sql"&gt;&lt;code&gt;&lt;span class="k"&gt;SELECT&lt;/span&gt; &lt;span class="k"&gt;table&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
       &lt;span class="n"&gt;formatReadableSize&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="k"&gt;sum&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;bytes_on_disk&lt;/span&gt;&lt;span class="p"&gt;))&lt;/span&gt; &lt;span class="k"&gt;AS&lt;/span&gt; &lt;span class="k"&gt;size&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
       &lt;span class="k"&gt;sum&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="k"&gt;rows&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="k"&gt;AS&lt;/span&gt; &lt;span class="k"&gt;rows&lt;/span&gt;
&lt;span class="k"&gt;FROM&lt;/span&gt; &lt;span class="k"&gt;system&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;parts&lt;/span&gt;
&lt;span class="k"&gt;WHERE&lt;/span&gt; &lt;span class="n"&gt;active&lt;/span&gt;
&lt;span class="k"&gt;GROUP&lt;/span&gt; &lt;span class="k"&gt;BY&lt;/span&gt; &lt;span class="k"&gt;table&lt;/span&gt;
&lt;span class="k"&gt;ORDER&lt;/span&gt; &lt;span class="k"&gt;BY&lt;/span&gt; &lt;span class="k"&gt;sum&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;bytes_on_disk&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="k"&gt;DESC&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Plan for it up front:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;Know your plan's limit.&lt;/strong&gt; Railway's Hobby plan caps storage at 5 GB; Pro raises it to 1 TB. A busy project can fill 5 GB of ClickHouse quickly.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Alert before it's full.&lt;/strong&gt; Langfuse's docs suggest alerting at 80%. Railway's volume metrics show usage per service.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Use retention.&lt;/strong&gt; Langfuse supports per-project data retention policies; check whether they're available on your edition.&lt;/li&gt;
&lt;/ul&gt;

&lt;h2&gt;
  
  
  Backups
&lt;/h2&gt;

&lt;p&gt;Two stores matter: Postgres (accounts, projects, prompts, API keys) and ClickHouse (all observability data). Redis holds only queues; S3 holds raw event payloads and media.&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;Railway volume backups.&lt;/strong&gt; Each volume's Backups tab schedules daily (kept 6 days), weekly (kept 27 days) and monthly (kept 89 days) incremental backups. Turn them on for the Postgres and ClickHouse volumes. They restore only within the same project and environment, so they don't protect against deleting the project.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Off-platform copies.&lt;/strong&gt; &lt;code&gt;pg_dump&lt;/code&gt; for Postgres (use a client at least as new as the server — 18 for the template). For ClickHouse, the native &lt;code&gt;BACKUP&lt;/code&gt; command can write straight to S3:
&lt;/li&gt;
&lt;/ul&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight sql"&gt;&lt;code&gt;  &lt;span class="n"&gt;BACKUP&lt;/span&gt; &lt;span class="k"&gt;DATABASE&lt;/span&gt; &lt;span class="k"&gt;default&lt;/span&gt;
  &lt;span class="k"&gt;TO&lt;/span&gt; &lt;span class="n"&gt;S3&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s1"&gt;'https://&amp;lt;endpoint&amp;gt;/&amp;lt;bucket&amp;gt;/backups/2026-11-06'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="s1"&gt;'&amp;lt;key&amp;gt;'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="s1"&gt;'&amp;lt;secret&amp;gt;'&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Restoring is the mirror image, &lt;code&gt;RESTORE DATABASE default FROM S3(...)&lt;/code&gt;.&lt;/p&gt;

&lt;p&gt;Losing Postgres is worse than losing ClickHouse: without it, your API keys, prompts and users are gone, even if every trace survives.&lt;/p&gt;

&lt;h2&gt;
  
  
  What it costs
&lt;/h2&gt;

&lt;p&gt;Railway bills per second: about $10 per GB of RAM per month, $20 per vCPU per month, and $0.16 per GB-month of volume storage. Hobby is $5/month including $5 of usage; Pro is $20/month including $20.&lt;/p&gt;

&lt;p&gt;Langfuse is RAM-heavy at idle — two Node.js processes, ClickHouse, Postgres and Redis all stay resident — so memory is most of the bill, and ClickHouse disk grows with what you ingest. A small instance runs on a few GB of RAM in total; every GB is roughly $10/month. After a week of real traffic, the Metrics tab for each service gives you the actual number for your workload.&lt;/p&gt;

&lt;h2&gt;
  
  
  When not to self-host it
&lt;/h2&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;You'd ingest a lot and nobody owns the database.&lt;/strong&gt; At high volume, ClickHouse needs real attention: disk, merges, memory. Langfuse itself recommends ClickHouse Cloud for larger deployments.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;You want it purely to save money at low volume.&lt;/strong&gt; Compare against Langfuse Cloud's pricing first; self-hosting pays off on data control first, cost second.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Your team can't upgrade SDKs.&lt;/strong&gt; v4 requires current SDKs; if you're pinned to Python SDK v2, stay on a v3 server until you can move.&lt;/li&gt;
&lt;/ul&gt;

&lt;h2&gt;
  
  
  Checklist
&lt;/h2&gt;

&lt;ul&gt;
&lt;li&gt;[ ] ClickHouse ≥ 25.12, pinned to a version tag&lt;/li&gt;
&lt;li&gt;[ ] &lt;code&gt;CLICKHOUSE_CLUSTER_ENABLED=false&lt;/code&gt; on web and worker&lt;/li&gt;
&lt;li&gt;[ ] ClickHouse listens on &lt;code&gt;::&lt;/code&gt; as well as &lt;code&gt;0.0.0.0&lt;/code&gt;
&lt;/li&gt;
&lt;li&gt;[ ] S3 event, media and export variables set; media endpoint reachable from browsers&lt;/li&gt;
&lt;li&gt;[ ] &lt;code&gt;NODE_OPTIONS=--max-old-space-size=...&lt;/code&gt; on web and worker&lt;/li&gt;
&lt;li&gt;[ ] Long health-check timeout for the first boot&lt;/li&gt;
&lt;li&gt;[ ] &lt;code&gt;AUTH_DISABLE_SIGNUP=true&lt;/code&gt; once your accounts exist&lt;/li&gt;
&lt;li&gt;[ ] Postgres and ClickHouse on UTC&lt;/li&gt;
&lt;li&gt;[ ] Python SDK ≥ 4.7.0 / JS SDK ≥ 5.4.0&lt;/li&gt;
&lt;li&gt;[ ] Disk alert on the ClickHouse volume&lt;/li&gt;
&lt;li&gt;[ ] Volume backups + off-platform &lt;code&gt;pg_dump&lt;/code&gt; and ClickHouse &lt;code&gt;BACKUP&lt;/code&gt;
&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;If something here is wrong or out of date, say so in the comments — I'll fix it.&lt;/p&gt;

</description>
      <category>llm</category>
      <category>selfhosted</category>
      <category>observability</category>
      <category>clickhouse</category>
    </item>
    <item>
      <title>Self-Hosting Chatwoot on Railway: What Actually Breaks (Email, Attachments, Sidekiq)</title>
      <dc:creator>Amritasha Agrawal</dc:creator>
      <pubDate>Fri, 06 Nov 2026 09:56:23 +0000</pubDate>
      <link>https://dev.to/amritasha_agrawal_a297c7d/self-hosting-chatwoot-on-railway-what-actually-breaks-email-attachments-sidekiq-37fh</link>
      <guid>https://dev.to/amritasha_agrawal_a297c7d/self-hosting-chatwoot-on-railway-what-actually-breaks-email-attachments-sidekiq-37fh</guid>
      <description>&lt;p&gt;Chatwoot is an open-source shared inbox — website live chat, email, WhatsApp, Telegram, Instagram and more, answered by a team from one dashboard. The self-hosted Community Edition is MIT-licensed, so there's no per-agent fee; you pay for the machine it runs on.&lt;/p&gt;

&lt;p&gt;"Self-host it" usually means renting a VPS, running Docker Compose, putting a reverse proxy in front and owning the patching. This guide is the other route: running it on Railway, a usage-billed platform where you get containers, managed volumes and private networking without a server to look after.&lt;/p&gt;

&lt;p&gt;The click-to-deploy part takes two minutes. The part worth reading is what doesn't work out of the box — because Chatwoot will look healthy while email, attachments or background jobs are silently broken.&lt;/p&gt;

&lt;h2&gt;
  
  
  What Chatwoot actually needs
&lt;/h2&gt;

&lt;p&gt;Chatwoot is a Rails app with four moving parts:&lt;/p&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Component&lt;/th&gt;
&lt;th&gt;Job&lt;/th&gt;
&lt;th&gt;What happens if it's missing&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;&lt;strong&gt;Rails web server&lt;/strong&gt;&lt;/td&gt;
&lt;td&gt;Dashboard, API, the chat widget's websocket&lt;/td&gt;
&lt;td&gt;Nothing loads&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;strong&gt;Sidekiq worker&lt;/strong&gt;&lt;/td&gt;
&lt;td&gt;Outbound email, webhooks, automation rules, reports, channel syncs&lt;/td&gt;
&lt;td&gt;UI works, but replies to email/social channels and every notification silently stop&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;strong&gt;PostgreSQL with pgvector&lt;/strong&gt;&lt;/td&gt;
&lt;td&gt;All conversations, contacts, settings&lt;/td&gt;
&lt;td&gt;—&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;strong&gt;Redis&lt;/strong&gt;&lt;/td&gt;
&lt;td&gt;Sidekiq's job queue and ActionCable pub/sub&lt;/td&gt;
&lt;td&gt;Nothing works&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;p&gt;Two details people trip on:&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;pgvector is mandatory since v4.&lt;/strong&gt; The migration that creates the Captain (AI) tables enables the &lt;code&gt;vector&lt;/code&gt; extension, and if it can't, it stops with &lt;em&gt;"Failed to enable 'vector' extension"&lt;/em&gt; — on a plain Postgres image your first deploy simply never finishes. Railway's managed Postgres image (&lt;code&gt;ghcr.io/railwayapp-templates/postgres-ssl&lt;/code&gt;) ships pgvector 0.8, so it works without a custom database.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;The web server and the worker are the same image.&lt;/strong&gt; The official Docker Compose file runs it twice: once as &lt;code&gt;rails s&lt;/code&gt;, once as &lt;code&gt;sidekiq&lt;/code&gt;. You can do the same on Railway (two services), or run both processes in one container to halve the idle cost. More on that trade-off below.&lt;/p&gt;

&lt;h2&gt;
  
  
  Decision 1: Outbound email — check your plan first
&lt;/h2&gt;

&lt;p&gt;This is the one that catches most people, and it's not a Chatwoot bug.&lt;/p&gt;

&lt;p&gt;Chatwoot sends mail through SMTP only. Look at &lt;code&gt;config/initializers/mailer.rb&lt;/code&gt;: the delivery method is &lt;code&gt;:smtp&lt;/code&gt;, falling back to &lt;code&gt;sendmail&lt;/code&gt; if &lt;code&gt;SMTP_ADDRESS&lt;/code&gt; is empty. There is no HTTP-API mail driver.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Railway blocks outbound SMTP (ports 25, 465, 587, 2525) on the Free, Trial and Hobby plans.&lt;/strong&gt; It's a platform-wide anti-spam policy, documented under &lt;a href="https://docs.railway.com/networking/outbound-networking" rel="noopener noreferrer"&gt;outbound networking&lt;/a&gt;, and support won't allowlist individual projects. On those plans, connections to SendGrid, Postmark, Gmail or any other SMTP host time out before they leave Railway.&lt;/p&gt;

&lt;p&gt;What that breaks in Chatwoot:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;Agent invites.&lt;/strong&gt; New agents get a confirmation email to set their password. No email, no way in.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Password resets.&lt;/strong&gt;&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Email notifications&lt;/strong&gt; to agents.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Replies on an Email inbox.&lt;/strong&gt; Chatwoot can receive email (IMAP or forwarding), but replies go out over SMTP — including when you configure per-inbox SMTP settings.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;What still works without email: the live-chat widget, WhatsApp, Telegram, Instagram/Facebook, the API — anything that isn't sending mail.&lt;/p&gt;

&lt;p&gt;Your options:&lt;/p&gt;

&lt;ol&gt;
&lt;li&gt;
&lt;strong&gt;Use the Pro plan&lt;/strong&gt; if email matters to you (it does for almost any real support team). SMTP is enabled on Pro and above.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Stay on Hobby and skip email&lt;/strong&gt;, e.g. if you only use the website widget or WhatsApp. You can still create agents without the invite email by setting their password from a Rails console:
&lt;/li&gt;
&lt;/ol&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;   railway ssh   &lt;span class="c"&gt;# into the Chatwoot service&lt;/span&gt;
   bundle &lt;span class="nb"&gt;exec &lt;/span&gt;rails runner &lt;span class="s1"&gt;'
     u = User.find_by(email: "agent@example.com")
     u.update!(password: "a-long-temporary-password", confirmed_at: Time.current)'&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Have them change the password after their first login.&lt;/p&gt;

&lt;p&gt;Either way, decide this before you invite your team, not after the first "I never got the email" message.&lt;/p&gt;

&lt;h2&gt;
  
  
  Decision 2: Where attachments live
&lt;/h2&gt;

&lt;p&gt;Every file a customer sends through the widget, every agent avatar, every email attachment goes through Rails Active Storage. Chatwoot picks the backend from &lt;code&gt;ACTIVE_STORAGE_SERVICE&lt;/code&gt;, and in production it defaults to &lt;code&gt;local&lt;/code&gt; — which means &lt;code&gt;/app/storage&lt;/code&gt; &lt;em&gt;inside the container&lt;/em&gt;.&lt;/p&gt;

&lt;p&gt;On any container platform, the container filesystem is thrown away on every redeploy. If nothing is mounted at &lt;code&gt;/app/storage&lt;/code&gt;, conversations survive (they're in Postgres) but &lt;strong&gt;every attachment and avatar disappears the next time the service restarts&lt;/strong&gt;, leaving broken image links throughout your history.&lt;/p&gt;

&lt;p&gt;Two correct setups:&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;A. A volume at &lt;code&gt;/app/storage&lt;/code&gt;&lt;/strong&gt; (simplest). Attach a Railway volume to the Chatwoot service with mount path &lt;code&gt;/app/storage&lt;/code&gt;, and leave &lt;code&gt;ACTIVE_STORAGE_SERVICE=local&lt;/code&gt;. Volume storage on Railway is billed per GB-month (about $0.16 at current rates) and can be included in Railway's scheduled backups (below). The limitation: a volume attaches to one service, so this only works if the web server and Sidekiq run in the same container — which is another reason for the single-container layout.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;B. An S3-compatible bucket&lt;/strong&gt; (better once you have real volume, or if you split web and worker into separate services). Chatwoot's &lt;code&gt;config/storage.yml&lt;/code&gt; defines two relevant backends, and the variable names matter — I've seen guides get these wrong:&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="c"&gt;# AWS S3&lt;/span&gt;
&lt;span class="nv"&gt;ACTIVE_STORAGE_SERVICE&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;amazon
&lt;span class="nv"&gt;S3_BUCKET_NAME&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;your-bucket
&lt;span class="nv"&gt;AWS_ACCESS_KEY_ID&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;...
&lt;span class="nv"&gt;AWS_SECRET_ACCESS_KEY&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;...
&lt;span class="nv"&gt;AWS_REGION&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;us-east-1

&lt;span class="c"&gt;# Anything S3-compatible (Cloudflare R2, MinIO, DigitalOcean Spaces, ...)&lt;/span&gt;
&lt;span class="nv"&gt;ACTIVE_STORAGE_SERVICE&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;s3_compatible
&lt;span class="nv"&gt;STORAGE_BUCKET_NAME&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;your-bucket
&lt;span class="nv"&gt;STORAGE_ACCESS_KEY_ID&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;...
&lt;span class="nv"&gt;STORAGE_SECRET_ACCESS_KEY&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;...
&lt;span class="nv"&gt;STORAGE_REGION&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;auto
&lt;span class="nv"&gt;STORAGE_ENDPOINT&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;https://&amp;lt;account-id&amp;gt;.r2.cloudflarestorage.com
&lt;span class="nv"&gt;STORAGE_FORCE_PATH_STYLE&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="nb"&gt;true&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Set them on every service that runs the Chatwoot image. Note that switching backends later doesn't move existing files — pick one before you have history worth keeping.&lt;/p&gt;

&lt;h2&gt;
  
  
  Decision 3: One container or two
&lt;/h2&gt;

&lt;p&gt;Running Rails and Sidekiq in one container saves memory and makes option A storage possible. The cost is that you can't scale or restart them independently, and you need something to keep Sidekiq alive.&lt;/p&gt;

&lt;p&gt;That last part is subtle. The obvious entrypoint script —&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="c"&gt;#!/bin/sh&lt;/span&gt;
&lt;span class="nb"&gt;set&lt;/span&gt; &lt;span class="nt"&gt;-e&lt;/span&gt;
bundle &lt;span class="nb"&gt;exec &lt;/span&gt;sidekiq &lt;span class="nt"&gt;-C&lt;/span&gt; config/sidekiq.yml &amp;amp;
&lt;span class="nb"&gt;exec &lt;/span&gt;bundle &lt;span class="nb"&gt;exec &lt;/span&gt;rails s &lt;span class="nt"&gt;-b&lt;/span&gt; 0.0.0.0
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;— has a nasty failure mode: if Sidekiq crashes, the web server keeps answering health checks, so the platform thinks everything is fine while every background job has stopped. Wrapping Sidekiq in a &lt;code&gt;while true&lt;/code&gt; restart loop fixes it, &lt;strong&gt;but only if the loop is immune to &lt;code&gt;set -e&lt;/code&gt;&lt;/strong&gt;. In a POSIX shell with &lt;code&gt;set -e&lt;/code&gt;, a backgrounded function exits on the first non-zero command — so a loop like this dies on the first crash and never restarts anything:&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;set&lt;/span&gt; &lt;span class="nt"&gt;-e&lt;/span&gt;
run_sidekiq&lt;span class="o"&gt;()&lt;/span&gt; &lt;span class="o"&gt;{&lt;/span&gt;
  &lt;span class="k"&gt;while &lt;/span&gt;&lt;span class="nb"&gt;true&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt; &lt;span class="k"&gt;do
    &lt;/span&gt;bundle &lt;span class="nb"&gt;exec &lt;/span&gt;sidekiq &lt;span class="nt"&gt;-C&lt;/span&gt; config/sidekiq.yml   &lt;span class="c"&gt;# non-zero exit kills the loop here&lt;/span&gt;
    &lt;span class="nb"&gt;echo&lt;/span&gt; &lt;span class="s2"&gt;"restarting"&lt;/span&gt;                           &lt;span class="c"&gt;# never reached&lt;/span&gt;
    &lt;span class="nb"&gt;sleep &lt;/span&gt;5
  &lt;span class="k"&gt;done&lt;/span&gt;
&lt;span class="o"&gt;}&lt;/span&gt;
run_sidekiq &amp;amp;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The fix is one change — capture the exit code so the shell doesn't treat it as fatal:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;run_sidekiq&lt;span class="o"&gt;()&lt;/span&gt; &lt;span class="o"&gt;{&lt;/span&gt;
  &lt;span class="k"&gt;while &lt;/span&gt;&lt;span class="nb"&gt;true&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt; &lt;span class="k"&gt;do
    &lt;/span&gt;&lt;span class="nv"&gt;code&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;0
    bundle &lt;span class="nb"&gt;exec &lt;/span&gt;sidekiq &lt;span class="nt"&gt;-C&lt;/span&gt; config/sidekiq.yml &lt;span class="o"&gt;||&lt;/span&gt; &lt;span class="nv"&gt;code&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="nv"&gt;$?&lt;/span&gt;
    &lt;span class="nb"&gt;echo&lt;/span&gt; &lt;span class="s2"&gt;"[chatwoot] Sidekiq exited with code &lt;/span&gt;&lt;span class="nv"&gt;$code&lt;/span&gt;&lt;span class="s2"&gt;, restarting in 5s"&lt;/span&gt;
    &lt;span class="nb"&gt;sleep &lt;/span&gt;5
  &lt;span class="k"&gt;done&lt;/span&gt;
&lt;span class="o"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;You can check this yourself in ten seconds: put &lt;code&gt;sh -c 'exit 3'&lt;/code&gt; in place of the Sidekiq command and run the script with and without &lt;code&gt;|| code=$?&lt;/code&gt;.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;When to split into two services:&lt;/strong&gt; once Sidekiq queues back up during busy hours (Chatwoot's Sidekiq dashboard at &lt;code&gt;/monitoring/sidekiq&lt;/code&gt; shows queue latency for super-admins), or once you want zero-downtime web deploys. Create a second service from the same image with the start command &lt;code&gt;bundle exec sidekiq -C config/sidekiq.yml&lt;/code&gt;, give it the same environment variables, and move attachments to option B, since the volume can't be shared.&lt;/p&gt;

&lt;h2&gt;
  
  
  Deploying it
&lt;/h2&gt;

&lt;p&gt;I maintain a Railway template that wires this up: Chatwoot (web + Sidekiq in one container), Railway Postgres with pgvector, and Redis with persistence. Database migrations run on boot.&lt;/p&gt;

&lt;p&gt;&lt;a href="https://railway.com/deploy/chatwoot-1?referralCode=Ib5Dqy&amp;amp;utm_medium=integration&amp;amp;utm_source=devto&amp;amp;utm_campaign=chatwoot-guide" rel="noopener noreferrer"&gt;&lt;img src="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Frailway.com%2Fbutton.svg" alt="Deploy on Railway" width="183" height="40"&gt;&lt;/a&gt;&lt;/p&gt;

&lt;p&gt;&lt;em&gt;(Disclosure: I earn a share of Railway usage from deployments of this template. Everything above applies equally if you build the services yourself.)&lt;/em&gt;&lt;/p&gt;

&lt;p&gt;After clicking deploy:&lt;/p&gt;

&lt;ol&gt;
&lt;li&gt;
&lt;strong&gt;Check storage.&lt;/strong&gt; Make sure the Chatwoot service has a volume mounted at &lt;code&gt;/app/storage&lt;/code&gt; (add one under the service's settings if not), or set the S3 variables from decision 2.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Set &lt;code&gt;SECRET_KEY_BASE&lt;/code&gt;.&lt;/strong&gt; Generate it with &lt;code&gt;openssl rand -hex 64&lt;/code&gt;. Don't change it later — it signs sessions and encrypts stored credentials.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Wait for the first boot.&lt;/strong&gt; &lt;code&gt;db:chatwoot_prepare&lt;/code&gt; creates and migrates the database before the web server binds its port. On a cold database this can take several minutes, which is why the health check timeout is set to 900 seconds; a shorter timeout kills the deploy mid-migration and leaves a half-migrated database.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Open the public URL and create the admin account.&lt;/strong&gt; A fresh install shows an onboarding form that creates the super-admin user — do this immediately, before anyone else finds the URL. Make sure &lt;code&gt;ENABLE_ACCOUNT_SIGNUP=false&lt;/code&gt; so strangers can't create their own accounts.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Check &lt;code&gt;FRONTEND_URL&lt;/code&gt;.&lt;/strong&gt; It defaults to the Railway domain. If you add a custom domain, update it — Chatwoot builds the widget script URL and every link in outgoing email from this value, so a stale one gives you a widget that won't load and password-reset links to a dead host.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Configure email&lt;/strong&gt; per decision 1 (Pro plan + SMTP variables).&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Create an inbox&lt;/strong&gt;, paste the widget snippet into your site, and send yourself a test message — including an attachment, then redeploy and confirm the attachment is still there.&lt;/li&gt;
&lt;/ol&gt;

&lt;h2&gt;
  
  
  Backups
&lt;/h2&gt;

&lt;p&gt;Your data lives in two places: Postgres (conversations, contacts, settings) and the &lt;code&gt;/app/storage&lt;/code&gt; volume (files), if you chose option A.&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;Railway volume backups.&lt;/strong&gt; Each volume's Backups tab lets you schedule daily (kept 6 days), weekly (kept 27 days) and monthly (kept 89 days) backups. They're incremental, billed for the unique data they hold, and restored with one click. Turn this on for both the Postgres volume and the storage volume.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Keep one copy off-platform.&lt;/strong&gt; Railway backups can only be restored inside the same project and environment, so they don't protect you from deleting the project. A periodic &lt;code&gt;pg_dump&lt;/code&gt; to somewhere else covers that:
&lt;/li&gt;
&lt;/ul&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;  pg_dump &lt;span class="s2"&gt;"&lt;/span&gt;&lt;span class="nv"&gt;$DATABASE_PUBLIC_URL&lt;/span&gt;&lt;span class="s2"&gt;"&lt;/span&gt; &lt;span class="nt"&gt;-Fc&lt;/span&gt; &lt;span class="nt"&gt;-f&lt;/span&gt; chatwoot-&lt;span class="si"&gt;$(&lt;/span&gt;&lt;span class="nb"&gt;date&lt;/span&gt; +%F&lt;span class="si"&gt;)&lt;/span&gt;.dump
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Use a &lt;code&gt;pg_dump&lt;/code&gt; client whose major version is at least the server's (18 for the template's Postgres).&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;Redis&lt;/strong&gt; holds queued jobs, not your data. The template's Redis snapshots every 60 seconds when anything changes, so a crash loses at most about a minute of not-yet-run jobs.&lt;/li&gt;
&lt;/ul&gt;

&lt;h2&gt;
  
  
  Upgrades
&lt;/h2&gt;

&lt;p&gt;The &lt;code&gt;chatwoot/chatwoot:latest&lt;/code&gt; tag moves with every release, and Chatwoot runs migrations automatically at boot — so on &lt;code&gt;latest&lt;/code&gt;, any redeploy (including one you triggered for an unrelated variable change) can upgrade you to a new version without warning.&lt;/p&gt;

&lt;p&gt;For a support tool your team relies on, pin a version instead: change the Dockerfile's &lt;code&gt;FROM&lt;/code&gt; line to a release tag (v4.19.1 at the time of writing), read the &lt;a href="https://github.com/chatwoot/chatwoot/releases" rel="noopener noreferrer"&gt;release notes&lt;/a&gt; before bumping it, and take a manual volume backup of Postgres first. Downgrades after a migration are not supported.&lt;/p&gt;

&lt;h2&gt;
  
  
  What it costs
&lt;/h2&gt;

&lt;p&gt;Railway bills per second for what the containers actually use: about $10 per GB of RAM per month, $20 per vCPU per month, and $0.16 per GB-month of volume storage. The Hobby plan is $5/month including $5 of usage; Pro is $20/month including $20 of usage.&lt;/p&gt;

&lt;p&gt;Chatwoot is a memory-resident app — Rails and Sidekiq sit in RAM whether or not anyone is chatting — so RAM is most of the bill, and it's roughly constant rather than tied to traffic. Every GB that the app, Postgres and Redis hold together adds about $10/month. Check your services' Metrics tab after a week; that number is the only one that matters for your instance.&lt;/p&gt;

&lt;p&gt;Compare that with per-seat SaaS pricing at your team size. The break-even point arrives fast with more than a couple of agents — but if you need SLAs, Captain AI features or someone else on call, Chatwoot's own cloud and premium self-hosted plans exist for that.&lt;/p&gt;

&lt;h2&gt;
  
  
  When not to do this
&lt;/h2&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;You need email and won't pay for a Pro-level plan.&lt;/strong&gt; On Hobby, Chatwoot can't send mail. Fix that first or pick another host.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Nobody on your team will ever read a log.&lt;/strong&gt; Self-hosting is cheap, not free: someone has to notice when a deploy fails or a channel token expires.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Compliance needs a signed agreement with your vendor.&lt;/strong&gt; Self-hosting gives you data control, not paperwork.&lt;/li&gt;
&lt;/ul&gt;

&lt;h2&gt;
  
  
  Checklist
&lt;/h2&gt;

&lt;ul&gt;
&lt;li&gt;[ ] Postgres has pgvector (first boot finishes)&lt;/li&gt;
&lt;li&gt;[ ] &lt;code&gt;SECRET_KEY_BASE&lt;/code&gt; set and saved somewhere safe&lt;/li&gt;
&lt;li&gt;[ ] Email: on a plan with SMTP, SMTP variables set, test invite received&lt;/li&gt;
&lt;li&gt;[ ] Storage: volume at &lt;code&gt;/app/storage&lt;/code&gt; &lt;strong&gt;or&lt;/strong&gt; S3/R2 variables — attachment survives a redeploy&lt;/li&gt;
&lt;li&gt;[ ] Sidekiq is supervised (or a separate service)&lt;/li&gt;
&lt;li&gt;[ ] &lt;code&gt;FRONTEND_URL&lt;/code&gt; matches the domain you actually use&lt;/li&gt;
&lt;li&gt;[ ] Volume backups scheduled for Postgres (and storage), plus an off-platform &lt;code&gt;pg_dump&lt;/code&gt;
&lt;/li&gt;
&lt;li&gt;[ ] Image pinned to a release tag&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;If something in here is wrong or out of date, tell me in the comments — I'd rather fix the article than have someone lose their attachments to it.&lt;/p&gt;

</description>
      <category>selfhosted</category>
      <category>opensource</category>
      <category>devops</category>
      <category>tutorial</category>
    </item>
    <item>
      <title>How to Self-Host Docmost on Railway — The Free Alternative to Notion ($16/mo)</title>
      <dc:creator>Amritasha Agrawal</dc:creator>
      <pubDate>Thu, 07 May 2026 07:27:51 +0000</pubDate>
      <link>https://dev.to/amritasha_agrawal_a297c7d/how-to-self-host-docmost-on-railway-the-free-alternative-to-notion-16mo-jhc</link>
      <guid>https://dev.to/amritasha_agrawal_a297c7d/how-to-self-host-docmost-on-railway-the-free-alternative-to-notion-16mo-jhc</guid>
      <description>&lt;p&gt;&lt;strong&gt;How to Self-Host Docmost on Railway — The Free Alternative to Notion ($16/mo)&lt;/strong&gt;&lt;/p&gt;

&lt;p&gt;If you're building a product or running a team, you need somewhere to put your docs. Notion is the obvious choice. Then you check the pricing — $16/mo per user — and do the math for a 10-person team.&lt;/p&gt;

&lt;p&gt;That's $160/mo just to write things down.&lt;/p&gt;

&lt;p&gt;Docmost is the open-source alternative. Real-time collaborative editing, nested pages, rich text, comments, permissions — everything you actually use in Notion. Self-hosted on Railway for around $5/mo total, regardless of how many users you have.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;What is Docmost?&lt;/strong&gt;&lt;/p&gt;

&lt;p&gt;Docmost is an open-source collaborative wiki and documentation platform. Think Notion or Confluence, but you own the data and pay for infrastructure only.&lt;/p&gt;

&lt;p&gt;It supports real-time collaborative editing, meaning multiple people can write in the same document at the same time — no conflicts, no refresh needed. You get nested pages, rich text formatting, image uploads, comments, workspaces, and role-based permissions.&lt;/p&gt;

&lt;p&gt;It's built for teams who want a clean knowledge base without paying per seat.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Pricing Comparison&lt;/strong&gt;&lt;/p&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Platform&lt;/th&gt;
&lt;th&gt;Price&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;Notion&lt;/td&gt;
&lt;td&gt;$16/mo per user&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Confluence&lt;/td&gt;
&lt;td&gt;$6.05/mo per user&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Coda&lt;/td&gt;
&lt;td&gt;$12/mo per user&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Outline&lt;/td&gt;
&lt;td&gt;$10/mo per user&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Docmost on Railway&lt;/td&gt;
&lt;td&gt;~$5/mo total&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;p&gt;A 10-person team on Notion costs $160/mo. The same team on self-hosted Docmost costs $5/mo.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;What You Get&lt;/strong&gt;&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;Real-time collaborative editing — multiple people, one document, no conflicts&lt;/li&gt;
&lt;li&gt;Nested pages — organize docs in a hierarchy that makes sense&lt;/li&gt;
&lt;li&gt;Rich text editor — headings, tables, code blocks, images, embeds&lt;/li&gt;
&lt;li&gt;Comments and mentions — discuss directly inside documents&lt;/li&gt;
&lt;li&gt;Workspaces — separate spaces for different teams or projects&lt;/li&gt;
&lt;li&gt;Role-based permissions — control who can read, write, or manage&lt;/li&gt;
&lt;li&gt;Full-text search — find anything across all your docs instantly&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;&lt;strong&gt;Deploy in 5 Minutes&lt;/strong&gt;&lt;/p&gt;

&lt;p&gt;Railway handles the infrastructure. PostgreSQL and Redis are provisioned automatically. The service is pre-exposed — no networking setup needed.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Step 1 — Click Deploy&lt;/strong&gt;&lt;/p&gt;

&lt;p&gt;&lt;a href="https://railway.com/deploy/docmost-1?referralCode=Ib5Dqy&amp;amp;utm_medium=integration&amp;amp;utm_source=template&amp;amp;utm_campaign=generic" rel="noopener noreferrer"&gt;https://railway.com/deploy/docmost-1?referralCode=Ib5Dqy&amp;amp;utm_medium=integration&amp;amp;utm_source=template&amp;amp;utm_campaign=generic&lt;/a&gt;&lt;/p&gt;

&lt;p&gt;This sets up Docmost, PostgreSQL, and Redis automatically.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Step 2 — Set one variable&lt;/strong&gt;&lt;/p&gt;

&lt;p&gt;Generate a secret key by running this in your terminal:&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;openssl rand -hex 64
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;

&lt;p&gt;Set APP_SECRET to the output. Everything else including your app URL is pre-configured.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Step 3 — Wait about 2 minutes&lt;/strong&gt;&lt;/p&gt;

&lt;p&gt;Railway builds the container and runs database migrations on first boot. You'll see the deployment go green in the dashboard.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Step 4 — Create your admin account&lt;/strong&gt;&lt;/p&gt;

&lt;p&gt;Open your Railway domain. Docmost walks you through account setup in about 30 seconds.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Step 5 — Create your first workspace&lt;/strong&gt;&lt;/p&gt;

&lt;p&gt;Add your team members, create pages, and start writing. The editor works like Notion — just start typing.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Optional: File Storage&lt;/strong&gt;&lt;/p&gt;

&lt;p&gt;By default files are stored locally. For production use, switch to S3:&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;STORAGE_DRIVER=s3
AWS_ACCESS_KEY_ID=your-key
AWS_SECRET_ACCESS_KEY=your-secret
AWS_REGION=us-east-1
AWS_BUCKET=your-bucket
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;

&lt;p&gt;Works with AWS S3, Cloudflare R2, or any S3-compatible provider.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;When to Move On&lt;/strong&gt;&lt;/p&gt;

&lt;p&gt;Docmost works well for most teams. If you need advanced features:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;Notion — databases, templates, and a huge ecosystem of integrations&lt;/li&gt;
&lt;li&gt;Confluence — deep Jira integration for engineering orgs&lt;/li&gt;
&lt;li&gt;Outline — another solid open-source option with a polished UI&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;Most teams won't hit Docmost's limits. It covers 95% of what people actually use Notion for.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Bottom Line&lt;/strong&gt;&lt;/p&gt;

&lt;p&gt;If your team needs a shared knowledge base and you're paying per seat, self-hosting is worth considering. Docmost gives you real-time collaboration, nested docs, and team permissions without the $160/mo bill.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Deploy it here: &lt;a href="https://railway.com/deploy/docmost-1?referralCode=Ib5Dqy&amp;amp;utm_medium=integration&amp;amp;utm_source=template&amp;amp;utm_campaign=generic" rel="noopener noreferrer"&gt;https://railway.com/deploy/docmost-1?referralCode=Ib5Dqy&amp;amp;utm_medium=integration&amp;amp;utm_source=template&amp;amp;utm_campaign=generic&lt;/a&gt;&lt;/strong&gt;&lt;/p&gt;

&lt;p&gt;&lt;em&gt;Amritasha builds open-source Railway templates for small businesses — deploy production-ready tools without the enterprise pricing. Connect on LinkedIn (&lt;a href="https://www.linkedin.com/in/amritasha/" rel="noopener noreferrer"&gt;https://www.linkedin.com/in/amritasha/&lt;/a&gt;) or reach out at &lt;a href="mailto:amritasha.ag@gmail.com"&gt;amritasha.ag@gmail.com&lt;/a&gt;&lt;/em&gt;&lt;/p&gt;

</description>
      <category>documentation</category>
      <category>opensource</category>
      <category>startup</category>
      <category>saas</category>
    </item>
    <item>
      <title>How to Self-Host Chatwoot on Railway - The Free Alternative to Intercom ($74/mo)</title>
      <dc:creator>Amritasha Agrawal</dc:creator>
      <pubDate>Thu, 07 May 2026 06:50:30 +0000</pubDate>
      <link>https://dev.to/amritasha_agrawal_a297c7d/how-to-self-host-chatwoot-on-railway-the-free-alternative-to-intercom-74mo-jid</link>
      <guid>https://dev.to/amritasha_agrawal_a297c7d/how-to-self-host-chatwoot-on-railway-the-free-alternative-to-intercom-74mo-jid</guid>
      <description>&lt;blockquote&gt;
&lt;p&gt;&lt;strong&gt;Update (Nov 2026):&lt;/strong&gt; I've written a more complete guide that covers two things this post misses: Railway blocks outbound SMTP on Free, Trial and Hobby plans (so invites and password resets won't send), and attachments are lost on every redeploy unless &lt;code&gt;/app/storage&lt;/code&gt; is on a volume. Read it here: &lt;a href="https://dev.to/amritasha_agrawal_a297c7d/self-hosting-chatwoot-on-railway-what-actually-breaks-email-attachments-sidekiq-37fh"&gt;Self-Hosting Chatwoot on Railway: What Actually Breaks&lt;/a&gt;&lt;/p&gt;
&lt;/blockquote&gt;

&lt;p&gt;&lt;strong&gt;How to Self-Host Chatwoot on Railway - The Free Alternative to Intercom ($74/mo)&lt;/strong&gt;&lt;/p&gt;

&lt;p&gt;If you're running a small business or SaaS and need a customer support inbox, you've probably looked at Intercom. Then you saw the pricing and closed the tab.&lt;/p&gt;

&lt;p&gt;Intercom starts at $74/mo per seat. Zendesk isn't much better. For a bootstrapped founder or small team, that's a real cost before you've even talked to a customer.&lt;/p&gt;

&lt;p&gt;Chatwoot is the open-source alternative. Same features: live chat, email inbox, WhatsApp, team assignments, canned responses, analytics. But you run it yourself, so you pay for infrastructure only. Not per agent, not per conversation.&lt;/p&gt;

&lt;p&gt;On Railway, that's roughly $5–10/mo total. No seat limits. No conversation caps.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;What is Chatwoot?&lt;/strong&gt;&lt;/p&gt;

&lt;p&gt;Chatwoot is an open-source customer support platform. It lets you manage all your customer conversations from a single shared inbox. Live chat, email, WhatsApp, Twitter, Facebook — all in one place.&lt;/p&gt;

&lt;p&gt;Your whole team can see incoming messages, assign conversations, reply, add internal notes, and track response times. It's what Intercom does, minus the enterprise pricing.&lt;/p&gt;

&lt;p&gt;It has 20,000+ GitHub stars and is actively maintained. This isn't a side project — it's production-ready software used by thousands of companies.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Pricing Comparison&lt;/strong&gt;&lt;/p&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Platform&lt;/th&gt;
&lt;th&gt;Price&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;Intercom&lt;/td&gt;
&lt;td&gt;$74+/mo per seat&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Zendesk&lt;/td&gt;
&lt;td&gt;$55+/mo per agent&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Freshdesk&lt;/td&gt;
&lt;td&gt;$15+/mo per agent&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Chatwoot Cloud&lt;/td&gt;
&lt;td&gt;$19/mo (5 agents)&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Chatwoot on Railway&lt;/td&gt;
&lt;td&gt;~$5–10/mo total&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;p&gt;A 5-person support team on Intercom costs $370+/mo. The same team on self-hosted Chatwoot costs $10/mo.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;What You Get&lt;/strong&gt;&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;Live chat widget — embed on any website in 2 minutes&lt;/li&gt;
&lt;li&gt;Email inbox — connect your support@ address&lt;/li&gt;
&lt;li&gt;WhatsApp, Twitter, Facebook integrations&lt;/li&gt;
&lt;li&gt;Team inbox — assign, label, and prioritize conversations&lt;/li&gt;
&lt;li&gt;Canned responses — reply faster with saved templates&lt;/li&gt;
&lt;li&gt;Reports — response times, volume, agent performance&lt;/li&gt;
&lt;li&gt;API access — connect to anything&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;&lt;strong&gt;Deploy in 5 Minutes&lt;/strong&gt;&lt;/p&gt;

&lt;p&gt;Railway handles the infrastructure. No servers to configure, no Docker knowledge needed.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Step 1 — Click Deploy&lt;/strong&gt;&lt;/p&gt;

&lt;p&gt;Use this link to get started:&lt;br&gt;
&lt;a href="https://railway.com/deploy/chatwoot-1?referralCode=Ib5Dqy&amp;amp;utm_medium=integration&amp;amp;utm_source=template&amp;amp;utm_campaign=generic" rel="noopener noreferrer"&gt;https://railway.com/deploy/chatwoot-1?referralCode=Ib5Dqy&amp;amp;utm_medium=integration&amp;amp;utm_source=template&amp;amp;utm_campaign=generic&lt;/a&gt;&lt;/p&gt;

&lt;p&gt;This sets up Chatwoot, PostgreSQL, and Redis automatically.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Step 2 — Set one variable&lt;/strong&gt;&lt;/p&gt;

&lt;p&gt;Generate a secret key by running this in your terminal:&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;openssl rand -hex 64
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;

&lt;p&gt;Paste the output as SECRET_KEY_BASE in Railway. FRONTEND_URL is already wired to your Railway domain automatically.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Step 3 — Wait about 2 minutes&lt;/strong&gt;&lt;/p&gt;

&lt;p&gt;Railway builds the container and runs database migrations on first boot. You'll see the deployment go green in the dashboard.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Step 4 — Create your admin account&lt;/strong&gt;&lt;/p&gt;

&lt;p&gt;Open your Railway domain. Chatwoot walks you through account setup in about 30 seconds.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Step 5 — Add your first inbox&lt;/strong&gt;&lt;/p&gt;

&lt;p&gt;Go to Settings → Inboxes → Add Inbox and pick your channel:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;Live Chat — paste the widget script into your website's head tag&lt;/li&gt;
&lt;li&gt;Email — connect your support@ address&lt;/li&gt;
&lt;li&gt;WhatsApp — connect via Twilio or the WhatsApp Cloud API&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;&lt;strong&gt;Optional: Email Notifications&lt;/strong&gt;&lt;/p&gt;

&lt;p&gt;To get invite emails and password reset emails working, add these to your Railway variables:&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;MAILER_SENDER_EMAIL=support@yourdomain.com
SMTP_ADDRESS=smtp.sendgrid.net
SMTP_PORT=587
SMTP_USERNAME=apikey
SMTP_PASSWORD=your-sendgrid-api-key
SMTP_AUTHENTICATION=plain
SMTP_ENABLE_STARTTLS_AUTO=true
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;

&lt;p&gt;Works with SendGrid, Resend, Postmark, or any SMTP provider.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;When to Move On&lt;/strong&gt;&lt;/p&gt;

&lt;p&gt;Chatwoot works well for teams up to around 50 agents. If you outgrow it:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;Intercom — polished and powerful, but $74+/mo per seat&lt;/li&gt;
&lt;li&gt;Zendesk — built for enterprise support, ticketing, SLAs&lt;/li&gt;
&lt;li&gt;Freshdesk — cheaper, has a free tier&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;Most small businesses won't hit those limits for years. And if you do, Chatwoot exports conversations as CSV so migrating is straightforward.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Bottom Line&lt;/strong&gt;&lt;/p&gt;

&lt;p&gt;You don't need to pay $74/mo per agent to run a proper support inbox. Chatwoot covers live chat, email, WhatsApp, and team collaboration for the cost of a Railway hobby plan.&lt;/p&gt;

&lt;p&gt;Deploy it here: &lt;a href="https://railway.com/deploy/chatwoot-1?referralCode=Ib5Dqy&amp;amp;utm_medium=integration&amp;amp;utm_source=template&amp;amp;utm_campaign=generic" rel="noopener noreferrer"&gt;https://railway.com/deploy/chatwoot-1?referralCode=Ib5Dqy&amp;amp;utm_medium=integration&amp;amp;utm_source=template&amp;amp;utm_campaign=generic&lt;/a&gt;&lt;/p&gt;

</description>
      <category>infrastructure</category>
      <category>opensource</category>
      <category>startup</category>
      <category>tutorial</category>
    </item>
  </channel>
</rss>
