<?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: octave Nkurunziza</title>
    <description>The latest articles on DEV Community by octave Nkurunziza (@octave_nkurunziza_afb0512).</description>
    <link>https://dev.to/octave_nkurunziza_afb0512</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%2F1847891%2F35ab1087-2f87-4c90-843e-cc2e9de399da.png</url>
      <title>DEV Community: octave Nkurunziza</title>
      <link>https://dev.to/octave_nkurunziza_afb0512</link>
    </image>
    <atom:link rel="self" type="application/rss+xml" href="https://dev.to/feed/octave_nkurunziza_afb0512"/>
    <language>en</language>
    <item>
      <title>Plausible vs Fathom vs Umami: which one costs less in 2026?</title>
      <dc:creator>octave Nkurunziza</dc:creator>
      <pubDate>Wed, 11 Nov 2026 16:21:53 +0000</pubDate>
      <link>https://dev.to/octave_nkurunziza_afb0512/plausible-vs-fathom-vs-umami-which-one-costs-less-in-2026-d1c</link>
      <guid>https://dev.to/octave_nkurunziza_afb0512/plausible-vs-fathom-vs-umami-which-one-costs-less-in-2026-d1c</guid>
      <description>&lt;p&gt;You want privacy-friendly analytics without a cookie banner, and it's down to Plausible vs Fathom vs Umami. All three count pageviews without cookies. The real difference is the bill: how each one counts your traffic, what happens when you go over, and whether running it yourself is cheaper. This guide puts all three on one price table at 10k, 100k, 1M and 10M monthly pageviews, then shows what the self-hosted versions cost on a real container platform.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Short answer:&lt;/strong&gt; under 100k pageviews, Umami Cloud's free plan is hard to beat. Around 1M, Umami Cloud Pro ($20) is the cheapest hosted option. If you want to run it yourself, Umami is the light one; Plausible Community Edition needs ClickHouse and about three times the resources.&lt;/p&gt;

&lt;p&gt;&lt;a href="https://hubfly.space/?ref=plausible-vs-fathom-vs-umami" rel="noopener noreferrer"&gt;Try it on Hubfly space&lt;/a&gt;&lt;/p&gt;

&lt;h2&gt;
  
  
  Plausible vs Fathom vs Umami: the price table
&lt;/h2&gt;

&lt;p&gt;All prices are monthly billing in USD, read from each official pricing page on 9 November 2026. Yearly billing is cheaper on Plausible and Fathom (both give two months free).&lt;/p&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Monthly pageviews&lt;/th&gt;
&lt;th&gt;
&lt;a href="https://plausible.io/#pricing" rel="noopener noreferrer"&gt;Plausible&lt;/a&gt; Starter (1 site)&lt;/th&gt;
&lt;th&gt;&lt;a href="https://usefathom.com/pricing" rel="noopener noreferrer"&gt;Fathom&lt;/a&gt;&lt;/th&gt;
&lt;th&gt;&lt;a href="https://umami.is/pricing" rel="noopener noreferrer"&gt;Umami Cloud&lt;/a&gt;&lt;/th&gt;
&lt;th&gt;Umami self-hosted on Hubfly space&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;10k&lt;/td&gt;
&lt;td&gt;$9&lt;/td&gt;
&lt;td&gt;$15 (smallest plan)&lt;/td&gt;
&lt;td&gt;$0 (Hobby)&lt;/td&gt;
&lt;td&gt;from $4.66 (starter size)&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;100k&lt;/td&gt;
&lt;td&gt;$19&lt;/td&gt;
&lt;td&gt;$15&lt;/td&gt;
&lt;td&gt;$0 (Hobby, 100k events cap)&lt;/td&gt;
&lt;td&gt;from $4.66 (starter size)&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;1M&lt;/td&gt;
&lt;td&gt;$69&lt;/td&gt;
&lt;td&gt;$60&lt;/td&gt;
&lt;td&gt;$20 (Pro)&lt;/td&gt;
&lt;td&gt;from $4.66 (starter size)&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;2M&lt;/td&gt;
&lt;td&gt;$89&lt;/td&gt;
&lt;td&gt;$100&lt;/td&gt;
&lt;td&gt;$50 (Pro + overage)&lt;/td&gt;
&lt;td&gt;size up&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;10M&lt;/td&gt;
&lt;td&gt;$169&lt;/td&gt;
&lt;td&gt;&lt;a href="https://usefathom.com/high-traffic" rel="noopener noreferrer"&gt;$200&lt;/a&gt;&lt;/td&gt;
&lt;td&gt;$200 (Business)&lt;/td&gt;
&lt;td&gt;size up&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;p&gt;The self-hosted price is the starting size; give it more RAM and disk as traffic grows.&lt;/p&gt;

&lt;p&gt;A few things the table hides:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;Plausible's price depends on the plan, not just traffic.&lt;/strong&gt; Starter covers one site. For up to 3 sites and team members you need Growth ($29 at 100k, $104 at 1M). Funnels, revenue and the Stats API are on Business ($39 at 100k, $139 at 1M).&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Fathom includes 50 sites on every plan&lt;/strong&gt; and has no free plan. Its high-traffic plans start at $140 for 5M and go to $470 for 25M.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Umami Cloud's Hobby plan is one website with 6 months of data.&lt;/strong&gt; Pro covers up to 20 websites and 2 years; Business adds unlimited sites and 5 years.&lt;/li&gt;
&lt;/ul&gt;

&lt;h2&gt;
  
  
  How each one counts your traffic
&lt;/h2&gt;

&lt;p&gt;This is where the cheap option can turn expensive.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Plausible&lt;/strong&gt; bills on pageviews plus custom events across all sites in a team. Custom events include outbound link clicks, file downloads, form submissions and 404 tracking (&lt;a href="https://plausible.io/docs/subscription-plans" rel="noopener noreferrer"&gt;Plausible docs&lt;/a&gt;). Turn on outbound-link tracking on a link-heavy site and your billable total can jump.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Fathom&lt;/strong&gt; works the same way: pageviews and custom events share one allowance across all your sites (&lt;a href="https://usefathom.com/pricing" rel="noopener noreferrer"&gt;Fathom pricing&lt;/a&gt;).&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Umami Cloud&lt;/strong&gt; counts pageviews, custom events, &lt;strong&gt;and every stored event property as one event each&lt;/strong&gt; (&lt;a href="https://umami.is/pricing" rel="noopener noreferrer"&gt;Umami pricing FAQ&lt;/a&gt;). That last part catches people.&lt;/p&gt;

&lt;p&gt;Here's a worked example. A site has 70,000 pageviews and 10,000 signup-button clicks a month. Each click is tracked with two properties (&lt;code&gt;plan&lt;/code&gt; and &lt;code&gt;source&lt;/code&gt;).&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;Plausible and Fathom count 70,000 + 10,000 = &lt;strong&gt;80,000&lt;/strong&gt;.&lt;/li&gt;
&lt;li&gt;Umami Cloud counts 70,000 + 10,000 + (10,000 × 2) = &lt;strong&gt;100,000&lt;/strong&gt; events.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;That's right at the Hobby cap. One more property and you're on Pro at $20. If you track events with properties, estimate Umami Cloud on events, not pageviews.&lt;/p&gt;

&lt;h2&gt;
  
  
  What happens when you go over
&lt;/h2&gt;

&lt;p&gt;All three are kinder about traffic spikes than most SaaS tools, but in different ways.&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;Plausible:&lt;/strong&gt; one month over your tier needs no action. Two months in a row and you're asked to upgrade; if you don't within a week, the dashboard locks. Stats keep being collected while it's locked (&lt;a href="https://plausible.io/docs/billing" rel="noopener noreferrer"&gt;Plausible billing FAQ&lt;/a&gt;).&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Fathom:&lt;/strong&gt; going over doesn't change your subscription automatically. They email you, and if usage stays high, dashboard and API access lock. Collection doesn't stop (&lt;a href="https://usefathom.com/docs/account/limits" rel="noopener noreferrer"&gt;Fathom limits&lt;/a&gt;).&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Umami Cloud:&lt;/strong&gt; no lock. Extra events are billed at $0.00003 each on Pro and $0.00002 on Business, and collection is never interrupted (&lt;a href="https://umami.is/pricing" rel="noopener noreferrer"&gt;Umami pricing&lt;/a&gt;).&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;Umami's model means a viral month costs money instead of locking your dashboard. On Pro, 2M events is $20 + 1,000,000 × $0.00003 = &lt;strong&gt;$50&lt;/strong&gt;.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;The Pro-to-Business crossover is 7M events.&lt;/strong&gt; Pro costs $20 + (events − 1M) × $0.00003. That equals Business's $200 when the overage is $180, which is 6M extra events, or 7M in total. Above 7M events a month, switch to Business; at 10M, Pro would be $290.&lt;/p&gt;

&lt;h2&gt;
  
  
  Where each one wins
&lt;/h2&gt;

&lt;p&gt;Be clear-eyed here. None of these is the best pick for everyone.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Pick Plausible if&lt;/strong&gt; you want a managed service with serious bot filtering and EU hosting. Plausible Cloud excludes around 32,000 data center IP ranges by default and keeps all visitor data on EU-owned infrastructure in Germany (&lt;a href="https://plausible.io/self-hosted-web-analytics" rel="noopener noreferrer"&gt;Plausible CE vs Cloud&lt;/a&gt;). For one site, Starter is also the cheapest of the paid options at 10k and at 10M pageviews on monthly billing. The 30-day trial needs no card.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Pick Fathom if&lt;/strong&gt; you run many small sites. 50 sites are included even on the $15 plan, so an agency with 30 client sites pays one bill. It also wins at 100k–1M if you'd otherwise need Plausible Growth for multiple sites. The trial is 7 days and needs a card.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Pick Umami Cloud if&lt;/strong&gt; you're under 100k events on one site (free), or around 1M events where Pro at $20 is a third of the others. Just count your event properties.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Pick self-hosted Umami if&lt;/strong&gt; you want a flat bill, full data ownership and you're fine running a small app and its database yourself. Umami is open source under the MIT license (&lt;a href="https://github.com/umami-software/umami" rel="noopener noreferrer"&gt;GitHub&lt;/a&gt;).&lt;/p&gt;

&lt;h2&gt;
  
  
  What self-hosting actually costs
&lt;/h2&gt;

&lt;p&gt;"Self-host it for free" is only half true. The software is free; the server isn't. Here are the two open-source options running on Hubfly space, priced from its public rates: $0.004 per vCPU-hour, $0.002 per GB-hour of RAM and $0.00001536 per GB-hour of storage, with 730 hours in a month.&lt;/p&gt;

&lt;h3&gt;
  
  
  Umami: about $4.66 a month
&lt;/h3&gt;

&lt;p&gt;Umami needs two services: the Umami app (the &lt;code&gt;postgresql-latest&lt;/code&gt; image, Next.js 16) and PostgreSQL 15. Hubfly space has an Umami preset in the Stack Composer. At its defaults (1 vCPU and 1 GB RAM per service) the estimate is $8.98 a month. Umami doesn't need that much to start, so drop both services to 0.5 vCPU and 512 MB.&lt;/p&gt;

&lt;p&gt;&lt;a href="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2F0orwc7eqhwpxe5k80s86.png" class="article-body-image-wrapper"&gt;&lt;img src="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2F0orwc7eqhwpxe5k80s86.png" alt="Umami stack in the Hubfly space Stack Composer at 0.5 vCPU and 512 MB per service, estimate $4.60 a month" width="799" height="448"&gt;&lt;/a&gt;&lt;/p&gt;

&lt;p&gt;The math per service:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;CPU: 0.5 × $0.004 × 730 = $1.46&lt;/li&gt;
&lt;li&gt;RAM: 0.5 GB × $0.002 × 730 = $0.73&lt;/li&gt;
&lt;li&gt;Container disk: 5 GB × $0.00001536 × 730 = $0.06&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Per service: $2.25&lt;/strong&gt;&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;Two services come to $4.49. The 10 GB database volume adds $0.11 at the Standard storage rate (10 × $0.00001536 × 730), so the composer shows &lt;strong&gt;$4.60&lt;/strong&gt;. After deploying, the project's budget panel projected &lt;strong&gt;$4.66 a month&lt;/strong&gt;.&lt;/p&gt;

&lt;p&gt;Once running, the app sat at about 40% of its 512 MB (roughly 210 MB) and Postgres at about 12% (roughly 60 MB), with plenty of headroom on both.&lt;/p&gt;

&lt;p&gt;&lt;a href="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Fpdzwxuj4r8c6jm5jxvou.png" class="article-body-image-wrapper"&gt;&lt;img src="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Fpdzwxuj4r8c6jm5jxvou.png" alt="Umami and Postgres running on Hubfly space: Umami at about 40% of 512 MB RAM, Postgres at about 12%" width="590" height="380"&gt;&lt;/a&gt;&lt;/p&gt;

&lt;p&gt;Deploying the stack took 42 seconds, and Umami applied its 26 database migrations on first boot.&lt;/p&gt;

&lt;h3&gt;
  
  
  Plausible Community Edition: about $13.53 a month, and it won't start as-is
&lt;/h3&gt;

&lt;p&gt;Plausible CE needs three services: the Plausible app, PostgreSQL for settings and users, and &lt;strong&gt;ClickHouse&lt;/strong&gt; for the event data. Plausible's own guide (CE v3.2.1) recommends at least 2 GB of RAM in total (&lt;a href="https://github.com/plausible/community-edition" rel="noopener noreferrer"&gt;plausible/community-edition&lt;/a&gt;).&lt;/p&gt;

&lt;p&gt;The Hubfly space preset (Plausible, ClickHouse and PostgreSQL 16) gives each service 1 vCPU and 1 GB:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;3 × (1 × $0.004 + 1 × $0.002) × 730 = $13.14 compute&lt;/li&gt;
&lt;li&gt;15 GB of container disk: $0.17&lt;/li&gt;
&lt;li&gt;Two 10 GB volumes: $0.22&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Total: $13.53 a month&lt;/strong&gt;&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;ClickHouse is the hungry one. With no data in it at all, it used about 62% of its 1 GB.&lt;/p&gt;

&lt;p&gt;&lt;a href="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Fjjpd5f16c1m5br1pvy7m.png" class="article-body-image-wrapper"&gt;&lt;img src="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Fjjpd5f16c1m5br1pvy7m.png" alt="Plausible CE stack: ClickHouse at about 62% of 1 GB RAM while empty, Postgres at 3%" width="799" height="353"&gt;&lt;/a&gt;&lt;/p&gt;

&lt;p&gt;So Plausible CE costs about three times as much to run as Umami at the starting size, before any traffic arrives.&lt;/p&gt;

&lt;p&gt;Also note the trade-offs Plausible lists for CE: no marketing funnels, user journeys, ecommerce revenue goals or SSO; simpler bot filtering; and releases about twice a year (&lt;a href="https://plausible.io/self-hosted-web-analytics" rel="noopener noreferrer"&gt;Plausible CE vs Cloud&lt;/a&gt;).&lt;/p&gt;

&lt;h3&gt;
  
  
  The work you take on
&lt;/h3&gt;

&lt;p&gt;The price above is only the server. Self-hosting also means:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;Upgrades and security fixes.&lt;/strong&gt; You apply them; nobody does it for you.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Backups.&lt;/strong&gt; Your analytics live in that Postgres (or ClickHouse) volume. Set a backup up on day one; see &lt;a href="https://www.hubfly.space/docs/volumes/?ref=plausible-vs-fathom-vs-umami" rel="noopener noreferrer"&gt;volumes&lt;/a&gt;.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Bot filtering.&lt;/strong&gt; A self-hosted instance only sees its own traffic, so it can't learn from other sites.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Growth.&lt;/strong&gt; At millions of pageviews a month, plan for more RAM and a bigger volume. Each extra GB of disk costs about $0.011 a month at the Standard rate, so storage stays cheap; RAM is what grows the bill.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;If that list sounds like a chore, a hosted plan is the honest answer.&lt;/p&gt;

&lt;h2&gt;
  
  
  What can go wrong
&lt;/h2&gt;

&lt;p&gt;&lt;strong&gt;Plausible CE crash-loops on first start.&lt;/strong&gt; The logs fill with:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;** (RuntimeError) BASE_URL configuration option is required.
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Plausible CE refuses to boot without &lt;code&gt;BASE_URL&lt;/code&gt;. Its &lt;a href="https://github.com/plausible/community-edition" rel="noopener noreferrer"&gt;setup guide&lt;/a&gt; lists &lt;code&gt;BASE_URL&lt;/code&gt; (your dashboard's public address, such as &lt;code&gt;https://stats.your-domain.com&lt;/code&gt;) and &lt;code&gt;SECRET_KEY_BASE&lt;/code&gt; (at least 64 bytes, for example from &lt;code&gt;openssl rand -base64 48&lt;/code&gt;) as required. The preset sets neither, so add both to the &lt;code&gt;plausible&lt;/code&gt; service before you deploy.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Umami logs "Can't reach database server" on the first boot.&lt;/strong&gt; The app can start before Postgres is accepting connections. Umami retries, and the next attempt applies the migrations and starts normally. If it keeps failing, check that &lt;code&gt;DATABASE_URL&lt;/code&gt; points at the database service's name and port 5432.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;You can still log in with &lt;code&gt;admin&lt;/code&gt; / &lt;code&gt;umami&lt;/code&gt;.&lt;/strong&gt; Umami creates that default account on first setup (&lt;a href="https://docs.umami.is/docs/install" rel="noopener noreferrer"&gt;Umami install docs&lt;/a&gt;). Change the password the moment you first log in, and set a strong database password and an &lt;code&gt;APP_SECRET&lt;/code&gt; of your own before you deploy (the preset ships sample values for both).&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Your Umami Cloud bill is higher than your pageviews.&lt;/strong&gt; Each stored event property counts as an event. Cut properties you never filter by, or move to Pro before you hit the Hobby cap.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Your Plausible or Fathom dashboard locks.&lt;/strong&gt; That's the overage rule, not an outage. Data is still being collected; upgrade (Plausible pro-rates the change) or wait for traffic to fall back within your tier.&lt;/p&gt;

&lt;h2&gt;
  
  
  FAQ
&lt;/h2&gt;

&lt;h3&gt;
  
  
  Is Plausible cheaper than Fathom?
&lt;/h3&gt;

&lt;p&gt;At 10k pageviews, yes ($9 vs $15). At 100k and 1M, Fathom is cheaper ($15 vs $19, $60 vs $69) on monthly billing. At 10M, Plausible Starter is cheaper ($169 vs $200). If you have more than one site, compare Fathom against Plausible Growth, not Starter.&lt;/p&gt;

&lt;h3&gt;
  
  
  Is Umami really free?
&lt;/h3&gt;

&lt;p&gt;The software is free and MIT-licensed if you host it yourself; you pay only for the server. Umami Cloud also has a free Hobby plan for one website and up to 100k events a month, with 6 months of data retention.&lt;/p&gt;

&lt;h3&gt;
  
  
  Do I need a cookie banner with Plausible, Fathom or Umami?
&lt;/h3&gt;

&lt;p&gt;All three say their cookieless tracking doesn't need one. You're still responsible for your own privacy policy and local rules, so read each vendor's privacy page before you remove a banner.&lt;/p&gt;

&lt;h3&gt;
  
  
  How much RAM does self-hosted Umami need?
&lt;/h3&gt;

&lt;p&gt;A fresh install idled at about 210 MB for the app and about 60 MB for Postgres, so 512 MB per service is a comfortable starting size. Give it more as your data and traffic grow.&lt;/p&gt;

&lt;h3&gt;
  
  
  Can I self-host Plausible on a small server?
&lt;/h3&gt;

&lt;p&gt;Plausible recommends at least 2 GB of RAM for the whole stack, because ClickHouse alone takes a big share. An empty ClickHouse used about 630 MB. A 1 GB server for all three services is asking for out-of-memory crashes.&lt;/p&gt;

&lt;h3&gt;
  
  
  Which one is best for a small blog?
&lt;/h3&gt;

&lt;p&gt;If you have one site under 100k pageviews, Umami Cloud's free plan. If you want a flat bill and own your data, self-hosted Umami for about $4.66 a month.&lt;/p&gt;

&lt;h2&gt;
  
  
  Go further on Hubfly space
&lt;/h2&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;Put your dashboard on your own domain.&lt;/strong&gt; Attach &lt;code&gt;stats.your-domain.com&lt;/code&gt; to the Umami container with HTTPS and no custom-domain fee. See &lt;a href="https://www.hubfly.space/docs/domains/?ref=plausible-vs-fathom-vs-umami" rel="noopener noreferrer"&gt;custom domains&lt;/a&gt;.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Cap the bill.&lt;/strong&gt; Set a monthly budget cap on the project so a runaway month can't surprise you. See &lt;a href="https://www.hubfly.space/docs/billing/?ref=plausible-vs-fathom-vs-umami" rel="noopener noreferrer"&gt;billing&lt;/a&gt;.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Keep the database safe.&lt;/strong&gt; Learn how project volumes and storage classes work before your analytics data grows. See &lt;a href="https://www.hubfly.space/docs/volumes/?ref=plausible-vs-fathom-vs-umami" rel="noopener noreferrer"&gt;volumes&lt;/a&gt;.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;Related reading: How to self host Umami analytics with Postgres · Cookieless analytics without a consent banner: how it works · &lt;a href="https://blog.hubfly.space/fixed-vs-pay-as-you-go-hosting-break-even?utm_source=devto&amp;amp;utm_medium=crosspost&amp;amp;utm_campaign=plausible-vs-fathom-vs-umami" rel="noopener noreferrer"&gt;Usage-based vs fixed pricing for hosting&lt;/a&gt;&lt;/p&gt;

&lt;p&gt;New accounts on Hubfly space make a one-time $5 deposit before creating resources. It's prepaid credit, not a fee, and it covers about a month of the Umami stack above.&lt;/p&gt;

&lt;p&gt;&lt;a href="https://hubfly.space/?ref=plausible-vs-fathom-vs-umami" rel="noopener noreferrer"&gt;Try it on Hubfly space&lt;/a&gt;&lt;/p&gt;




&lt;p&gt;&lt;em&gt;By Octave · drafted with AI, tested on Hubfly · Last updated 9 November 2026&lt;/em&gt;&lt;/p&gt;

</description>
      <category>analytics</category>
      <category>privacy</category>
      <category>selfhosted</category>
      <category>webdev</category>
    </item>
    <item>
      <title>Google Workspace alternatives for small business email (2026)</title>
      <dc:creator>octave Nkurunziza</dc:creator>
      <pubDate>Wed, 11 Nov 2026 16:21:09 +0000</pubDate>
      <link>https://dev.to/octave_nkurunziza_afb0512/google-workspace-alternatives-for-small-business-email-2026-195f</link>
      <guid>https://dev.to/octave_nkurunziza_afb0512/google-workspace-alternatives-for-small-business-email-2026-195f</guid>
      <description>&lt;p&gt;Most small teams don't need an office suite. They need five people to have real addresses on their own domain, and somewhere for support@ and sales@ to land. Google Workspace charges for every person, every month, whether they use Docs or not. This guide compares the Google Workspace alternatives for small business email on one question: what does a 5-person team with two shared inboxes pay in year one, and what do you give up for the lower price? By the end you'll know which one fits your team and the exact bill.&lt;/p&gt;

&lt;p&gt;&lt;a href="https://www.hubfly.space/?ref=google-workspace-alternatives-small-business-email" rel="noopener noreferrer"&gt;Try it on Hubfly space&lt;/a&gt;&lt;/p&gt;

&lt;h2&gt;
  
  
  The team in every price below
&lt;/h2&gt;

&lt;p&gt;Every number below uses the same setup, so the totals are comparable:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;5 people, each with their own address (&lt;code&gt;amina@your-domain.com&lt;/code&gt;).&lt;/li&gt;
&lt;li&gt;2 shared addresses: &lt;code&gt;support@&lt;/code&gt; and &lt;code&gt;sales@&lt;/code&gt;, read by 2–3 people each.&lt;/li&gt;
&lt;li&gt;1 custom domain.&lt;/li&gt;
&lt;li&gt;Annual billing where a provider offers it, because that's the cheaper option and the one most small teams pick.&lt;/li&gt;
&lt;li&gt;List prices in USD, read from each provider's official pricing page on 10 November 2026. Taxes not included.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;If your team is bigger, multiply the per-person prices. The flat-price options don't move.&lt;/p&gt;

&lt;h2&gt;
  
  
  Google Workspace alternatives for small business: the price table
&lt;/h2&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Provider and plan&lt;/th&gt;
&lt;th&gt;Price (as listed)&lt;/th&gt;
&lt;th&gt;5-person team, year one&lt;/th&gt;
&lt;th&gt;Storage&lt;/th&gt;
&lt;th&gt;Works with Outlook / Apple Mail&lt;/th&gt;
&lt;th&gt;Shared inboxes&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;&lt;a href="https://knowledge.workspace.google.com/admin/billing/compare-flexible-and-annual-fixed-term-payment-plans" rel="noopener noreferrer"&gt;Google Workspace Business Starter&lt;/a&gt;&lt;/td&gt;
&lt;td&gt;$7/user/month on the annual plan, $8.40 on the flexible plan&lt;/td&gt;
&lt;td&gt;&lt;strong&gt;$420&lt;/strong&gt;&lt;/td&gt;
&lt;td&gt;30 GB pooled per user&lt;/td&gt;
&lt;td&gt;&lt;a href="https://support.google.com/mail/answer/7126229" rel="noopener noreferrer"&gt;Yes&lt;/a&gt;&lt;/td&gt;
&lt;td&gt;Google Groups (&lt;a href="https://support.google.com/a/users/answer/167430" rel="noopener noreferrer"&gt;Collaborative Inbox&lt;/a&gt;)&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;a href="https://www.microsoft.com/en-us/microsoft-365/business/compare-all-microsoft-365-business-products" rel="noopener noreferrer"&gt;Microsoft 365 Business Basic&lt;/a&gt;&lt;/td&gt;
&lt;td&gt;$7.00/user/month, paid yearly&lt;/td&gt;
&lt;td&gt;&lt;strong&gt;$420&lt;/strong&gt;&lt;/td&gt;
&lt;td&gt;100 GB mailbox per user&lt;/td&gt;
&lt;td&gt;Basic: web and mobile apps only&lt;/td&gt;
&lt;td&gt;&lt;a href="https://learn.microsoft.com/en-us/microsoft-365/admin/email/about-shared-mailboxes" rel="noopener noreferrer"&gt;Shared mailboxes need no license up to 50 GB&lt;/a&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;a href="https://proton.me/business/mail/pricing" rel="noopener noreferrer"&gt;Proton Mail Essentials&lt;/a&gt;&lt;/td&gt;
&lt;td&gt;$6.99/user/month, billed $83.88 a year&lt;/td&gt;
&lt;td&gt;&lt;strong&gt;$419.40&lt;/strong&gt;&lt;/td&gt;
&lt;td&gt;15 GB per user&lt;/td&gt;
&lt;td&gt;Yes (Outlook, Thunderbird, Apple Mail)&lt;/td&gt;
&lt;td&gt;Email groups only on Workspace plans&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;a href="https://www.fastmail.com/pricing/" rel="noopener noreferrer"&gt;Fastmail Standard&lt;/a&gt;&lt;/td&gt;
&lt;td&gt;$5/user/month yearly, $6 monthly&lt;/td&gt;
&lt;td&gt;&lt;strong&gt;$300&lt;/strong&gt;&lt;/td&gt;
&lt;td&gt;60 GB per user&lt;/td&gt;
&lt;td&gt;Yes, third-party apps like Outlook and iPhone Mail&lt;/td&gt;
&lt;td&gt;Shared addresses included&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;a href="https://www.migadu.com/pricing/" rel="noopener noreferrer"&gt;Migadu Mini&lt;/a&gt;&lt;/td&gt;
&lt;td&gt;$90/year flat, not per mailbox&lt;/td&gt;
&lt;td&gt;&lt;strong&gt;$90&lt;/strong&gt;&lt;/td&gt;
&lt;td&gt;30 GB (soft limit)&lt;/td&gt;
&lt;td&gt;&lt;a href="https://www.migadu.com/" rel="noopener noreferrer"&gt;Yes, IMAP and POP3&lt;/a&gt;&lt;/td&gt;
&lt;td&gt;Not priced per mailbox&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;a href="https://www.zoho.com/mail/zohomail-pricing.html" rel="noopener noreferrer"&gt;Zoho Mail Lite 5 GB&lt;/a&gt;&lt;/td&gt;
&lt;td&gt;$1/user/month, yearly only&lt;/td&gt;
&lt;td&gt;&lt;strong&gt;$60&lt;/strong&gt;&lt;/td&gt;
&lt;td&gt;5 GB per user&lt;/td&gt;
&lt;td&gt;Free plan: no IMAP/POP; check Lite&lt;/td&gt;
&lt;td&gt;Per user&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;a href="https://purelymail.com/pricing" rel="noopener noreferrer"&gt;Purelymail&lt;/a&gt;&lt;/td&gt;
&lt;td&gt;$10/year&lt;/td&gt;
&lt;td&gt;&lt;strong&gt;$10&lt;/strong&gt;&lt;/td&gt;
&lt;td&gt;Soft limits&lt;/td&gt;
&lt;td&gt;&lt;a href="https://purelymail.com/" rel="noopener noreferrer"&gt;Yes, IMAP or POP3&lt;/a&gt;&lt;/td&gt;
&lt;td&gt;No hard limit on users or domains&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;a href="https://www.hubfly.space/docs/mail/pricing-and-limits/?ref=google-workspace-alternatives-small-business-email" rel="noopener noreferrer"&gt;Hubfly space Mail&lt;/a&gt;&lt;/td&gt;
&lt;td&gt;Free mailboxes, $2 once per custom domain&lt;/td&gt;
&lt;td&gt;&lt;strong&gt;$2&lt;/strong&gt;&lt;/td&gt;
&lt;td&gt;1 GB shared by the whole project&lt;/td&gt;
&lt;td&gt;No: web and API only&lt;/td&gt;
&lt;td&gt;Shared mailboxes with roles, free&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;p&gt;&lt;a href="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Fbbmh6c3njmkrtftnf3d8.png" class="article-body-image-wrapper"&gt;&lt;img src="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Fbbmh6c3njmkrtftnf3d8.png" alt="Bar chart of first-year business email cost for a 5-person team across eight providers" width="800" height="420"&gt;&lt;/a&gt;&lt;/p&gt;

&lt;p&gt;Two things jump out. First, the three big names cost almost the same: about $420 a year for five people. Second, the cheap options are cheap for a reason, and the reason is different for each one. The rest of this guide is about those reasons.&lt;/p&gt;

&lt;h2&gt;
  
  
  How each price works (and the catch)
&lt;/h2&gt;

&lt;h3&gt;
  
  
  Google Workspace: you're paying for the suite
&lt;/h3&gt;

&lt;p&gt;Business Starter is &lt;strong&gt;$7 per user per month on a 1-year commitment&lt;/strong&gt;, or &lt;strong&gt;$8.40 on the flexible monthly plan&lt;/strong&gt;. Five people on the annual plan is 5 × $7 × 12 = &lt;strong&gt;$420&lt;/strong&gt;. On the flexible plan it's 5 × $8.40 × 12 = &lt;strong&gt;$504&lt;/strong&gt;.&lt;/p&gt;

&lt;p&gt;What you get for that: Gmail, 30 GB pooled storage per person, Meet, Drive and Docs. If your team lives in Docs and Meet all day, Workspace is fair value and none of the options below replace it.&lt;/p&gt;

&lt;p&gt;The catch: the annual plan locks you in. Google's billing help page says you "must pay full commitment (even if you cancel early)". If you might shrink or switch, the flexible plan costs 20% more.&lt;/p&gt;

&lt;p&gt;For support@, Google's answer is a Google Group with Collaborative Inbox turned on, which lets group members with the right permissions work incoming mail together.&lt;/p&gt;

&lt;h3&gt;
  
  
  Microsoft 365 Business Basic: the best deal on shared inboxes
&lt;/h3&gt;

&lt;p&gt;Business Basic is &lt;strong&gt;$7.00 per user per month, paid yearly&lt;/strong&gt;: the same $420 for five people. You get Outlook on the web and mobile and a 100 GB mailbox per person.&lt;/p&gt;

&lt;p&gt;Here Microsoft wins a point that most comparisons miss: &lt;strong&gt;a shared mailbox can store up to 50 GB without a license of its own&lt;/strong&gt;. So support@ and sales@ don't need seats of their own. If shared inboxes are the main reason you want team email and you like Outlook, this is the strongest big-name option.&lt;/p&gt;

&lt;p&gt;The catch: Basic gives you the web and mobile Office apps only. For desktop apps you move up to Business Standard, listed at $23.50 per user per month with Copilot.&lt;/p&gt;

&lt;h3&gt;
  
  
  Proton Mail Essentials: privacy at big-name prices
&lt;/h3&gt;

&lt;p&gt;Mail Essentials is &lt;strong&gt;$6.99 per user per month, billed $83.88 a year&lt;/strong&gt; per user. Five people: 5 × $83.88 = &lt;strong&gt;$419.40&lt;/strong&gt;. You get encrypted email, 15 GB per person, 10 addresses per user and 3 custom domains. Proton lists Outlook, Thunderbird and Apple Mail as supported.&lt;/p&gt;

&lt;p&gt;Proton's pricing page shows a 40% first-year discount on its Workspace plans until 30 November 2026, but not on Mail Essentials, so it isn't counted here.&lt;/p&gt;

&lt;p&gt;The catch: "Email groups" are listed only on the higher Workspace plans. On Essentials, plan on aliases or forwarding for support@ rather than a group inbox.&lt;/p&gt;

&lt;h3&gt;
  
  
  Fastmail Standard: the polished middle ground
&lt;/h3&gt;

&lt;p&gt;Fastmail's Standard plan is &lt;strong&gt;$5 per user per month on yearly billing&lt;/strong&gt; ($60 a year per person) or $6 month to month. Five people: 5 × $60 = &lt;strong&gt;$300&lt;/strong&gt;. You get 60 GB each, custom domains and shared addresses like support@ included.&lt;/p&gt;

&lt;p&gt;Fastmail is the closest thing to "Gmail, but just email": a fast web app, its own apps, and support for third-party apps like Outlook and iPhone Mail. If you want polished mail and nothing else, it's the safest pick on this list.&lt;/p&gt;

&lt;p&gt;The catch: it's still per person. At 20 people you're at $1,200 a year.&lt;/p&gt;

&lt;h3&gt;
  
  
  Migadu: flat price, daily sending caps
&lt;/h3&gt;

&lt;p&gt;Migadu doesn't charge per mailbox at all. In its own words: "The plan prices are flat, per Migadu account." The Mini plan is &lt;strong&gt;$90 a year&lt;/strong&gt; (or $9 a month) and allows 1,000 incoming and 100 outgoing messages a day across the whole account, with 30 GB of soft storage.&lt;/p&gt;

&lt;p&gt;That changes the maths. Five people or fifteen, it's $90.&lt;/p&gt;

&lt;p&gt;The catch: the sending cap is shared. Five people sending 25 emails each on a busy day hits 125, over Mini's 100. The Micro plan ($19 a year) only allows 20 outgoing messages a day, which is too few for most teams.&lt;/p&gt;

&lt;h3&gt;
  
  
  Zoho Mail: the cheapest per-seat option
&lt;/h3&gt;

&lt;p&gt;Zoho Mail Lite with 5 GB is &lt;strong&gt;$1 per user per month, billed yearly only&lt;/strong&gt;. Five people: 5 × $1 × 12 = &lt;strong&gt;$60&lt;/strong&gt;. The 10 GB tier is $1.25. Mail Premium, with 50 GB, is $4.&lt;/p&gt;

&lt;p&gt;Zoho's Forever Free plan covers &lt;strong&gt;up to 5 users&lt;/strong&gt; with 5 GB each on one domain, so a team of exactly five pays nothing. Zoho's page is clear about the trade: "IMAP/ POP/ Active Sync not included" on the free plan, so it's Zoho's web and mobile apps, not Outlook or Apple Mail. And "From the 6th user all users enter a paid plan."&lt;/p&gt;

&lt;p&gt;The catch: Zoho lists different USD prices for some regions, including Africa and the Middle East, so check the price for your billing country before you commit.&lt;/p&gt;

&lt;h3&gt;
  
  
  Purelymail: almost free, almost no frills
&lt;/h3&gt;

&lt;p&gt;Purelymail is &lt;strong&gt;$10 a year&lt;/strong&gt;, and its pricing page says: "There are no hard limits. Not on users, custom domains, storage, or anything else." Heavy use moves you to pay-per-resource pricing.&lt;/p&gt;

&lt;p&gt;It's a no-frills service: great for technical people who want mail on their own domain, in any mail client, at almost no cost. Less great if the person setting it up isn't comfortable with DNS records.&lt;/p&gt;

&lt;h3&gt;
  
  
  Hubfly space Mail: shared inboxes for the price of a domain
&lt;/h3&gt;

&lt;p&gt;&lt;a href="https://www.hubfly.space/docs/mail/?ref=google-workspace-alternatives-small-business-email" rel="noopener noreferrer"&gt;Hubfly space Mail&lt;/a&gt; is built around team inboxes rather than seats. The &lt;a href="https://www.hubfly.space/docs/mail/pricing-and-limits/?ref=google-workspace-alternatives-small-business-email" rel="noopener noreferrer"&gt;pricing page&lt;/a&gt; is short: "Mailboxes, people and incoming mail are free. You pay $2 once for each custom domain."&lt;/p&gt;

&lt;p&gt;For the 5-person team, that's:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;1 Mail project: free.&lt;/li&gt;
&lt;li&gt;5 personal mailboxes + 2 shared mailboxes (support@, sales@): free, up to 200 mailboxes per project.&lt;/li&gt;
&lt;li&gt;Inbound mail and forwarding: free and unlimited.&lt;/li&gt;
&lt;li&gt;Custom domain: &lt;strong&gt;$2, once&lt;/strong&gt;.&lt;/li&gt;
&lt;li&gt;Sending on the custom domain: free tier, 30 recipients a minute, 100 an hour and 500 a day.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;Year one: &lt;strong&gt;$2&lt;/strong&gt;. Year two: $0. Charges come from a prepaid balance, and creating your first resources needs a one-time deposit of $5 or more. It's credit, not a fee: the $2 domain fee comes out of it and $3 stays in your balance.&lt;/p&gt;

&lt;p&gt;Shared mailboxes come with roles (read, full, owner), so two people can work support@ without sharing a password. Replies go out from the address the customer wrote to.&lt;/p&gt;

&lt;p&gt;The catches are real, so here they are plainly:&lt;/p&gt;

&lt;ol&gt;
&lt;li&gt;
&lt;strong&gt;1 GB of storage for the whole project&lt;/strong&gt;, shared by every mailbox. Across 5 personal and 2 shared mailboxes, that's about 140 MB each. Fine for support and sales threads; not fine for years of attachments. Extra storage at $0.10 per GB a month is listed as coming soon, not for sale yet.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;No IMAP or POP, by design.&lt;/strong&gt; You read mail in the browser at mailbox.hubmail.space or through the Mailbox API. No Outlook or Apple Mail.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;No calendar, docs or video calls.&lt;/strong&gt; It's email only.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Up to 6 Mail projects per account.&lt;/strong&gt; The dashboard stops you at the seventh:&lt;/li&gt;
&lt;/ol&gt;

&lt;p&gt;&lt;a href="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2F66d0tvjc1ditdazxjrun.png" class="article-body-image-wrapper"&gt;&lt;img src="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2F66d0tvjc1ditdazxjrun.png" alt="Hubfly space Create Project dialog with Mail selected, showing the limit of 6 Mail projects" width="660" height="460"&gt;&lt;/a&gt;&lt;/p&gt;

&lt;p&gt;If your team wants a shared support@ inbox, a few personal addresses and a low bill, and is happy in a web inbox, it fits. If you need Outlook, a calendar or big mailboxes, pick Fastmail or Microsoft 365 instead.&lt;/p&gt;

&lt;h2&gt;
  
  
  Which one should you pick?
&lt;/h2&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;If your team...&lt;/th&gt;
&lt;th&gt;Pick&lt;/th&gt;
&lt;th&gt;Why&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;Lives in Docs, Sheets and Meet&lt;/td&gt;
&lt;td&gt;Google Workspace&lt;/td&gt;
&lt;td&gt;You're paying for the suite, and it's good&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Wants Outlook and free shared inboxes&lt;/td&gt;
&lt;td&gt;Microsoft 365 Business Basic&lt;/td&gt;
&lt;td&gt;Shared mailboxes need no license up to 50 GB&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Handles sensitive client mail&lt;/td&gt;
&lt;td&gt;Proton Mail Essentials&lt;/td&gt;
&lt;td&gt;Privacy-focused encrypted email&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Wants great email and nothing else&lt;/td&gt;
&lt;td&gt;Fastmail Standard&lt;/td&gt;
&lt;td&gt;Polished mail, works with Outlook, 60 GB each&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Is growing but sends little&lt;/td&gt;
&lt;td&gt;Migadu Mini&lt;/td&gt;
&lt;td&gt;One flat price for any number of mailboxes&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Has 5 people or fewer and uses the browser&lt;/td&gt;
&lt;td&gt;Zoho Mail Forever Free&lt;/td&gt;
&lt;td&gt;$0, web and mobile only&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Is technical and wants IMAP for pennies&lt;/td&gt;
&lt;td&gt;Purelymail&lt;/td&gt;
&lt;td&gt;$10 a year&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Mostly needs shared support@ and sales@ inboxes&lt;/td&gt;
&lt;td&gt;Hubfly space Mail&lt;/td&gt;
&lt;td&gt;Free mailboxes and roles, $2 once per domain&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;p&gt;A good rule of thumb: count how many people need a &lt;strong&gt;personal&lt;/strong&gt; inbox versus how many just need to &lt;strong&gt;answer&lt;/strong&gt; &lt;a href="mailto:support@"&gt;support@&lt;/a&gt;. Per-seat pricing punishes the second group. Microsoft, Migadu and Hubfly space don't charge for shared inboxes; Google, Proton, Fastmail and Zoho mostly price by person.&lt;/p&gt;

&lt;h2&gt;
  
  
  What can go wrong when you switch
&lt;/h2&gt;

&lt;p&gt;&lt;strong&gt;Mail stops arriving after the switch.&lt;/strong&gt; You changed MX records but the old provider's records are still cached. MX changes can take hours to spread. Lower the TTL on your MX records to 300 seconds a day before you switch, and keep the old account open for a week.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Your mail lands in spam.&lt;/strong&gt; You now have two SPF records, one for the old provider and one for the new. A domain may have only one SPF record; two make SPF fail. Merge them into a single &lt;code&gt;v=spf1 include:... include:... ~all&lt;/code&gt; line, then remove the old provider's part once you're fully moved. Set up DKIM and DMARC with the values your new provider gives you.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Old mail is gone.&lt;/strong&gt; Moving MX records doesn't copy anything. Export first: Google Takeout for Gmail, or an IMAP sync tool to copy mailbox to mailbox. If the new provider has no IMAP (Zoho free, Hubfly space Mail), keep the archive in the old account or a local mail client instead of importing it.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;The free plan becomes a paid plan overnight.&lt;/strong&gt; Zoho's free plan is 5 users. The sixth user moves &lt;em&gt;everyone&lt;/em&gt; to a paid plan. Plan your headcount before you pick a free tier.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Support@ goes quiet when someone leaves.&lt;/strong&gt; If support@ is just an alias that forwards to one person's inbox, their leaving breaks it. Use a real shared mailbox or group, so the inbox outlives any one person.&lt;/p&gt;

&lt;h2&gt;
  
  
  FAQ
&lt;/h2&gt;

&lt;h3&gt;
  
  
  What is the cheapest alternative to Google Workspace for business email?
&lt;/h3&gt;

&lt;p&gt;For a 5-person team, Zoho Mail Forever Free ($0, web only) and Hubfly space Mail ($2 once per domain, web only) are the cheapest. Among paid plans, Purelymail ($10 a year) and Zoho Mail Lite ($60 a year for five people) are the cheapest.&lt;/p&gt;

&lt;h3&gt;
  
  
  Is Microsoft 365 cheaper than Google Workspace for email?
&lt;/h3&gt;

&lt;p&gt;Not per person: both entry plans are $7 per user per month on annual billing. Microsoft can be cheaper overall because shared mailboxes like support@ don't need their own license up to 50 GB.&lt;/p&gt;

&lt;h3&gt;
  
  
  Can I get a professional email address for free?
&lt;/h3&gt;

&lt;p&gt;Yes. Zoho Mail's Forever Free plan covers up to 5 users on one custom domain. Hubfly space Mail gives free mailboxes and asks $2 once to add your custom domain. You still pay for the domain name itself at your registrar.&lt;/p&gt;

&lt;h3&gt;
  
  
  Do I need one paid user for support@ and sales@?
&lt;/h3&gt;

&lt;p&gt;It depends on the provider. Microsoft 365 shared mailboxes don't need a license up to 50 GB. Migadu and Hubfly space don't charge per mailbox at all. On per-person plans, use an alias or group instead of a full user where the provider supports it.&lt;/p&gt;

&lt;h3&gt;
  
  
  Can I keep using Outlook or Apple Mail?
&lt;/h3&gt;

&lt;p&gt;Gmail, Proton, Migadu and Purelymail all work with standard mail apps, and Fastmail lists third-party apps like Outlook and iPhone Mail. Microsoft 365 Business Basic gives you web and mobile apps only. Zoho's free plan has no IMAP, and Hubfly space Mail is web and API only. Check each provider's setup page before you switch.&lt;/p&gt;

&lt;h3&gt;
  
  
  How do I move my email from Google Workspace without losing anything?
&lt;/h3&gt;

&lt;p&gt;Export with Google Takeout or copy mailboxes over IMAP, lower your MX TTL a day ahead, switch MX, SPF, DKIM and DMARC to the new provider, and keep Workspace for a week to catch stragglers before you cancel.&lt;/p&gt;

&lt;h2&gt;
  
  
  Go further on Hubfly space
&lt;/h2&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;a href="https://www.hubfly.space/docs/mail/mailboxes/?ref=google-workspace-alternatives-small-business-email" rel="noopener noreferrer"&gt;Create a shared support@ mailbox&lt;/a&gt;: turn on mailboxes, create a Shared mailbox and give teammates read or full access.&lt;/li&gt;
&lt;li&gt;
&lt;a href="https://www.hubfly.space/docs/mail/routing/?ref=google-workspace-alternatives-small-business-email" rel="noopener noreferrer"&gt;Route support@ and sales@ with forwarding rules&lt;/a&gt;: send a copy to a phone-friendly inbox, or catch everything with a wildcard.&lt;/li&gt;
&lt;li&gt;
&lt;a href="https://www.hubfly.space/docs/mail/custom-domains/?ref=google-workspace-alternatives-small-business-email" rel="noopener noreferrer"&gt;Add your custom domain and DNS records&lt;/a&gt;: the ownership TXT, MX, SPF, DKIM and DMARC steps, checked one by one.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;Related reading: &lt;a href="https://blog.hubfly.space/fixed-vs-pay-as-you-go-hosting-break-even?utm_source=devto&amp;amp;utm_medium=crosspost&amp;amp;utm_campaign=google-workspace-alternatives-small-business-email" rel="noopener noreferrer"&gt;Fixed vs pay-as-you-go hosting: find your break-even point&lt;/a&gt; and &lt;a href="https://blog.hubfly.space/root-domain-custom-domain?utm_source=devto&amp;amp;utm_medium=crosspost&amp;amp;utm_campaign=google-workspace-alternatives-small-business-email" rel="noopener noreferrer"&gt;How to use your root domain as a custom domain&lt;/a&gt;.&lt;/p&gt;

&lt;p&gt;&lt;a href="https://www.hubfly.space/?ref=google-workspace-alternatives-small-business-email" rel="noopener noreferrer"&gt;Try it on Hubfly space&lt;/a&gt;&lt;/p&gt;




&lt;p&gt;&lt;em&gt;By Octave · drafted with AI, reviewed by Octave · Last updated 10 November 2026&lt;/em&gt;&lt;/p&gt;

</description>
      <category>email</category>
      <category>smallbusiness</category>
      <category>productivity</category>
      <category>devops</category>
    </item>
    <item>
      <title>How to add WebRTC live streaming to your website (under 1 s)</title>
      <dc:creator>octave Nkurunziza</dc:creator>
      <pubDate>Wed, 11 Nov 2026 16:21:08 +0000</pubDate>
      <link>https://dev.to/octave_nkurunziza_afb0512/how-to-add-webrtc-live-streaming-to-your-website-under-1-s-345d</link>
      <guid>https://dev.to/octave_nkurunziza_afb0512/how-to-add-webrtc-live-streaming-to-your-website-under-1-s-345d</guid>
      <description>&lt;p&gt;&lt;a href="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2F4dl6se7danzm6kvdys8v.png" class="article-body-image-wrapper"&gt;&lt;img src="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2F4dl6se7danzm6kvdys8v.png" alt="Diagram: a broadcaster sends video over WHIP to a stream server, and your website plays it over WHEP 0.8–0.9 seconds behind live" width="800" height="450"&gt;&lt;/a&gt;&lt;/p&gt;

&lt;p&gt;You want live video on your own website, and you want it &lt;strong&gt;live&lt;/strong&gt;: a viewer asks a question in chat and sees the answer a second later, not half a minute later. Normal HLS players run 15–25 seconds behind. Even low-latency HLS sits at a few seconds. WebRTC live streaming on your website gets that under one second, and since WHIP and WHEP (plain HTTP for WebRTC) arrived, you don't need a signalling server or an SDK.&lt;/p&gt;

&lt;p&gt;By the end of this guide you'll have a stream server, a broadcast going out from a browser tab, and a small WebRTC player on your site that reconnects on its own and shows when you're offline. Expect the picture to reach viewers in &lt;strong&gt;under a second&lt;/strong&gt;: 0.8–0.9 s on a connection with a 0.4 s round trip.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;&lt;a href="https://www.hubfly.space/?ref=webrtc-live-streaming-website" rel="noopener noreferrer"&gt;Try it on Hubfly space&lt;/a&gt;&lt;/strong&gt;. A 25 Mbps stream server costs nothing to run if it's your only one; viewer bandwidth beyond 50 GB a month is billed (see What it costs).&lt;/p&gt;

&lt;h2&gt;
  
  
  What you need
&lt;/h2&gt;

&lt;ul&gt;
&lt;li&gt;A Hubfly space account. You'll use Hubfly space Managed Streams for the media server.&lt;/li&gt;
&lt;li&gt;A Chromium-based browser such as Chrome or Edge (the steps below use Chrome 154).&lt;/li&gt;
&lt;li&gt;A web page you control. Any static host works; the player is one HTML file.&lt;/li&gt;
&lt;/ul&gt;

&lt;h2&gt;
  
  
  How WebRTC live streaming on a website works
&lt;/h2&gt;

&lt;p&gt;There are three parts, and each one speaks plain HTTPS to set up a WebRTC connection:&lt;/p&gt;

&lt;ol&gt;
&lt;li&gt;
&lt;strong&gt;The broadcaster&lt;/strong&gt; sends video &lt;em&gt;in&lt;/em&gt; over &lt;strong&gt;WHIP&lt;/strong&gt; (WebRTC-HTTP Ingestion Protocol). This guide uses the Dashboard's own browser broadcaster.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;The stream server&lt;/strong&gt; receives it, and a &lt;strong&gt;channel&lt;/strong&gt; turns it into player links: WebRTC, LL-HLS, HLS, an embed page and a status file.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Your page&lt;/strong&gt; pulls video &lt;em&gt;out&lt;/em&gt; over &lt;strong&gt;WHEP&lt;/strong&gt; (WebRTC-HTTP Egress Protocol): it POSTs an SDP offer, gets an SDP answer, and the browser does the rest.&lt;/li&gt;
&lt;/ol&gt;

&lt;p&gt;Nothing about your page needs a WebSocket, a media library or a build step.&lt;/p&gt;

&lt;h2&gt;
  
  
  Step 1: Create a stream server
&lt;/h2&gt;

&lt;p&gt;A stream server is the media relay your viewers connect to. You need one before you have any URLs.&lt;/p&gt;

&lt;ol&gt;
&lt;li&gt;In the Dashboard, click &lt;strong&gt;Create Project&lt;/strong&gt;, name it (for example &lt;code&gt;live-site&lt;/code&gt;), choose &lt;strong&gt;Managed service&lt;/strong&gt; and click &lt;strong&gt;Create Project&lt;/strong&gt;.&lt;/li&gt;
&lt;li&gt;On the project page, find &lt;strong&gt;Streams&lt;/strong&gt; and click &lt;strong&gt;Create a stream server&lt;/strong&gt;.&lt;/li&gt;
&lt;li&gt;Pick a speed. &lt;strong&gt;25 Mbps&lt;/strong&gt; is the free tier and is enough to get started and for about five HD viewers. You can change it later.&lt;/li&gt;
&lt;li&gt;Leave &lt;strong&gt;Create a push input&lt;/strong&gt; on and name the input &lt;code&gt;studio-cam&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;Enter an instance name such as &lt;code&gt;live-site&lt;/code&gt; and click &lt;strong&gt;Create stream server&lt;/strong&gt;.&lt;/li&gt;
&lt;/ol&gt;

&lt;p&gt;The server is ready in a few seconds. A dialog shows the input's &lt;strong&gt;stream key&lt;/strong&gt; once. Treat it like a password: anyone who has it can broadcast on your channel. Store it in your password manager, tick the box and click &lt;strong&gt;Done&lt;/strong&gt;.&lt;/p&gt;

&lt;p&gt;Your server gets a hostname like &lt;code&gt;live-site-4c06.live.hubfly.app&lt;/code&gt;. You'll use it in every URL below.&lt;/p&gt;

&lt;h2&gt;
  
  
  Step 2: Add a channel set to ultra-low latency
&lt;/h2&gt;

&lt;p&gt;The channel is what viewers watch. Its latency setting decides whether browsers get WebRTC.&lt;/p&gt;

&lt;ol&gt;
&lt;li&gt;Open &lt;strong&gt;Channels&lt;/strong&gt; and click &lt;strong&gt;Add channel&lt;/strong&gt;.&lt;/li&gt;
&lt;li&gt;Name it &lt;code&gt;Main&lt;/code&gt;. Under &lt;strong&gt;Plays&lt;/strong&gt;, pick &lt;code&gt;studio-cam&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;Keep &lt;strong&gt;Pass-through&lt;/strong&gt; under Quality. It sends exactly what the broadcaster sends, and it costs nothing to process.&lt;/li&gt;
&lt;li&gt;Under &lt;strong&gt;Latency&lt;/strong&gt;, choose &lt;strong&gt;Ultra-low latency&lt;/strong&gt;. The default is &lt;em&gt;Low latency&lt;/em&gt; (LL-HLS, 3–5 s), so don't skip this.&lt;/li&gt;
&lt;li&gt;Make sure &lt;strong&gt;WebRTC (WHEP)&lt;/strong&gt; is on, keep &lt;strong&gt;Public&lt;/strong&gt; access for now, and click &lt;strong&gt;Add channel&lt;/strong&gt;.&lt;/li&gt;
&lt;/ol&gt;

&lt;p&gt;&lt;a href="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Flw8ppofp8y3t3nxqgv8l.png" class="article-body-image-wrapper"&gt;&lt;img src="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Flw8ppofp8y3t3nxqgv8l.png" alt="The Add channel dialog with Pass-through quality and Ultra-low latency selected" width="672" height="685"&gt;&lt;/a&gt;&lt;/p&gt;

&lt;p&gt;Open the channel and scroll to &lt;strong&gt;Links and embed&lt;/strong&gt;. Copy the &lt;strong&gt;WebRTC (WHEP)&lt;/strong&gt; URL. It looks like &lt;code&gt;https://live-site-4c06.live.hubfly.app/whep/sch_0179428b74b2635b&lt;/code&gt;. The last part, starting with &lt;code&gt;sch_&lt;/code&gt;, is your channel ID.&lt;/p&gt;

&lt;p&gt;&lt;a href="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Fdmm25t9tymk8r8ntruh8.png" class="article-body-image-wrapper"&gt;&lt;img src="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Fdmm25t9tymk8r8ntruh8.png" alt="The channel's Links and embed section showing the embed page, HLS, WebRTC (WHEP) and thumbnail URLs" width="770" height="725"&gt;&lt;/a&gt;&lt;/p&gt;

&lt;h2&gt;
  
  
  Step 3: Go live from a browser tab
&lt;/h2&gt;

&lt;p&gt;You don't need OBS to start. The Dashboard can publish your camera or screen over WHIP, and it handles the stream key for you.&lt;/p&gt;

&lt;ol&gt;
&lt;li&gt;Open &lt;strong&gt;Studio&lt;/strong&gt; and scroll to &lt;strong&gt;Go live from this browser&lt;/strong&gt;.&lt;/li&gt;
&lt;li&gt;Pick the input (&lt;code&gt;studio-cam&lt;/code&gt;), then &lt;strong&gt;Camera&lt;/strong&gt; or &lt;strong&gt;Screen&lt;/strong&gt;, and keep the video bitrate at &lt;strong&gt;2,500 kbps&lt;/strong&gt;.&lt;/li&gt;
&lt;li&gt;Click &lt;strong&gt;Go live&lt;/strong&gt;. Your browser asks for camera (or screen) access the first time.&lt;/li&gt;
&lt;/ol&gt;

&lt;p&gt;Within a few seconds the badge reads &lt;strong&gt;Publishing&lt;/strong&gt; with the current bitrate, and the channel switches to &lt;strong&gt;Live&lt;/strong&gt; on its own. The browser sends H.264 video and Opus audio. It may start at a low resolution and step up to 1280×720 once it has measured your upload speed.&lt;/p&gt;

&lt;p&gt;&lt;a href="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Fwzkw0xtxlqwsk0g5xsvx.png" class="article-body-image-wrapper"&gt;&lt;img src="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Fwzkw0xtxlqwsk0g5xsvx.png" alt="Go live from this browser, publishing a clock picture to the studio-cam input" width="500" height="420"&gt;&lt;/a&gt;&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Prefer OBS?&lt;/strong&gt; The input's page (&lt;strong&gt;Inputs → studio-cam&lt;/strong&gt;) shows the OBS settings, and the &lt;a href="https://www.hubfly.space/docs/streams/obs-and-encoders/?ref=webrtc-live-streaming-website" rel="noopener noreferrer"&gt;OBS and encoders guide&lt;/a&gt; covers WHIP from OBS. Keep B-frames off, or browsers can't play the stream over WebRTC.&lt;/p&gt;

&lt;h2&gt;
  
  
  Step 4: The quickest player: the embed page
&lt;/h2&gt;

&lt;p&gt;If you just want video on a page right now, paste the channel's embed code:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight html"&gt;&lt;code&gt;&lt;span class="nt"&gt;&amp;lt;iframe&lt;/span&gt;
  &lt;span class="na"&gt;src&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="s"&gt;"https://live-site-4c06.live.hubfly.app/embed/sch_0179428b74b2635b?autoplay=1&amp;amp;muted=1"&lt;/span&gt;
  &lt;span class="na"&gt;style&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="s"&gt;"width:100%;aspect-ratio:16/9;border:0"&lt;/span&gt;
  &lt;span class="na"&gt;allow&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="s"&gt;"autoplay; fullscreen; picture-in-picture"&lt;/span&gt;
  &lt;span class="na"&gt;allowfullscreen&lt;/span&gt;&lt;span class="nt"&gt;&amp;gt;&amp;lt;/iframe&amp;gt;&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The embed page shows a &lt;strong&gt;LIVE&lt;/strong&gt; badge and an &lt;strong&gt;Unmute&lt;/strong&gt; button, and on an ultra-low latency channel it prefers WebRTC. Browsers only autoplay video that starts muted, which is why &lt;code&gt;muted=1&lt;/code&gt; is there.&lt;/p&gt;

&lt;p&gt;Use the embed when you're happy with its look. Write your own player (next step) when you want your own controls, your own offline screen, or a viewer count in your page.&lt;/p&gt;

&lt;h2&gt;
  
  
  Step 5: Write your own WebRTC player with WHEP
&lt;/h2&gt;

&lt;p&gt;This is the whole player. Save it as &lt;code&gt;live.html&lt;/code&gt;, replace the two constants at the top with your hostname and channel ID, and open it from any web server.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight html"&gt;&lt;code&gt;&lt;span class="nt"&gt;&amp;lt;video&lt;/span&gt; &lt;span class="na"&gt;id&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="s"&gt;"live"&lt;/span&gt; &lt;span class="na"&gt;autoplay&lt;/span&gt; &lt;span class="na"&gt;muted&lt;/span&gt; &lt;span class="na"&gt;playsinline&lt;/span&gt; &lt;span class="na"&gt;controls&lt;/span&gt; &lt;span class="na"&gt;style&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="s"&gt;"width:100%;max-width:960px;background:#000"&lt;/span&gt;&lt;span class="nt"&gt;&amp;gt;&amp;lt;/video&amp;gt;&lt;/span&gt;
&lt;span class="nt"&gt;&amp;lt;p&lt;/span&gt; &lt;span class="na"&gt;id&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="s"&gt;"state"&lt;/span&gt;&lt;span class="nt"&gt;&amp;gt;&lt;/span&gt;Connecting…&lt;span class="nt"&gt;&amp;lt;/p&amp;gt;&lt;/span&gt;

&lt;span class="nt"&gt;&amp;lt;script&lt;/span&gt; &lt;span class="na"&gt;type&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="s"&gt;"module"&lt;/span&gt;&lt;span class="nt"&gt;&amp;gt;&lt;/span&gt;
  &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="no"&gt;HOST&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;"https://live-site-4c06.live.hubfly.app"&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="no"&gt;CHANNEL&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;"sch_0179428b74b2635b"&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

  &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="n"&gt;video&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nb"&gt;document&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;getElementById&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s2"&gt;"live"&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="n"&gt;label&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nb"&gt;document&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;getElementById&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s2"&gt;"state"&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

  &lt;span class="c1"&gt;// Wait until the browser has listed its network addresses (2 s at most).&lt;/span&gt;
  &lt;span class="kd"&gt;function&lt;/span&gt; &lt;span class="nf"&gt;iceGatheringDone&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;pc&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="k"&gt;if&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;pc&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;iceGatheringState&lt;/span&gt; &lt;span class="o"&gt;===&lt;/span&gt; &lt;span class="s2"&gt;"complete"&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="nb"&gt;Promise&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;resolve&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
    &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="k"&gt;new&lt;/span&gt; &lt;span class="nb"&gt;Promise&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;resolve&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="o"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
      &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="n"&gt;timer&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nb"&gt;setTimeout&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;resolve&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="mi"&gt;2000&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
      &lt;span class="n"&gt;pc&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;addEventListener&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s2"&gt;"icegatheringstatechange"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="o"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
        &lt;span class="k"&gt;if&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;pc&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;iceGatheringState&lt;/span&gt; &lt;span class="o"&gt;===&lt;/span&gt; &lt;span class="s2"&gt;"complete"&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
          &lt;span class="nf"&gt;clearTimeout&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;timer&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
          &lt;span class="nf"&gt;resolve&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
        &lt;span class="p"&gt;}&lt;/span&gt;
      &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
    &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="p"&gt;}&lt;/span&gt;

  &lt;span class="c1"&gt;// WHEP: post an offer, get an answer back, keep the session URL.&lt;/span&gt;
  &lt;span class="k"&gt;async&lt;/span&gt; &lt;span class="kd"&gt;function&lt;/span&gt; &lt;span class="nf"&gt;connect&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="n"&gt;pc&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;new&lt;/span&gt; &lt;span class="nc"&gt;RTCPeerConnection&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
    &lt;span class="n"&gt;pc&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;addTransceiver&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s2"&gt;"video"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="n"&gt;direction&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"recvonly"&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
    &lt;span class="n"&gt;pc&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;addTransceiver&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s2"&gt;"audio"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="n"&gt;direction&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"recvonly"&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

    &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="n"&gt;stream&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;new&lt;/span&gt; &lt;span class="nc"&gt;MediaStream&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
    &lt;span class="n"&gt;pc&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;ontrack&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;event&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="o"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="n"&gt;stream&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;addTrack&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;event&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;track&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
    &lt;span class="n"&gt;video&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;srcObject&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="n"&gt;stream&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

    &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="n"&gt;pc&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;setLocalDescription&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="n"&gt;pc&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;createOffer&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
    &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="nf"&gt;iceGatheringDone&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;pc&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

    &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="n"&gt;res&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="nb"&gt;fetch&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="sb"&gt;`${HOST}/whep/${CHANNEL}`&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
      &lt;span class="n"&gt;method&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"POST"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
      &lt;span class="n"&gt;headers&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="s2"&gt;"Content-Type"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"application/sdp"&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
      &lt;span class="n"&gt;body&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="n"&gt;pc&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;localDescription&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;sdp&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
    &lt;span class="k"&gt;if&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;res&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;status&lt;/span&gt; &lt;span class="o"&gt;!==&lt;/span&gt; &lt;span class="mi"&gt;201&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
      &lt;span class="n"&gt;pc&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;close&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
      &lt;span class="k"&gt;throw&lt;/span&gt; &lt;span class="k"&gt;new&lt;/span&gt; &lt;span class="nb"&gt;Error&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="sb"&gt;`WHEP ${res.status}`&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
    &lt;span class="p"&gt;}&lt;/span&gt;
    &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="n"&gt;session&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;new&lt;/span&gt; &lt;span class="no"&gt;URL&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;res&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;headers&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;get&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s2"&gt;"Location"&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="no"&gt;HOST&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;href&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
    &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="n"&gt;pc&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;setRemoteDescription&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="kd"&gt;type&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"answer"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;sdp&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="n"&gt;res&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;text&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
    &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="n"&gt;pc&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;session&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="p"&gt;}&lt;/span&gt;

  &lt;span class="c1"&gt;// Hang up cleanly so the server frees the seat and the viewer count stays right.&lt;/span&gt;
  &lt;span class="kd"&gt;function&lt;/span&gt; &lt;span class="nf"&gt;hangUp&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="n"&gt;pc&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;session&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="n"&gt;pc&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;close&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
    &lt;span class="nb"&gt;fetch&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;session&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="n"&gt;method&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"DELETE"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;keepalive&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kc"&gt;true&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="k"&gt;catch&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="o"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;&lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="p"&gt;}&lt;/span&gt;

  &lt;span class="kd"&gt;let&lt;/span&gt; &lt;span class="n"&gt;current&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="kc"&gt;null&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

  &lt;span class="k"&gt;async&lt;/span&gt; &lt;span class="kd"&gt;function&lt;/span&gt; &lt;span class="nf"&gt;start&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="k"&gt;try&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
      &lt;span class="n"&gt;label&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;textContent&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;"Connecting…"&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
      &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="n"&gt;mine&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;current&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="nf"&gt;connect&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
      &lt;span class="n"&gt;mine&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;pc&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;onconnectionstatechange&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="o"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
        &lt;span class="k"&gt;if&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;mine&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;pc&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;connectionState&lt;/span&gt; &lt;span class="o"&gt;===&lt;/span&gt; &lt;span class="s2"&gt;"connected"&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="nf"&gt;showStatus&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
        &lt;span class="k"&gt;if&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;mine&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;pc&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;connectionState&lt;/span&gt; &lt;span class="o"&gt;===&lt;/span&gt; &lt;span class="s2"&gt;"failed"&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
          &lt;span class="nf"&gt;hangUp&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;mine&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
          &lt;span class="n"&gt;label&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;textContent&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;"Connection lost. Reconnecting…"&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
          &lt;span class="nb"&gt;setTimeout&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;start&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="mi"&gt;2000&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
        &lt;span class="p"&gt;}&lt;/span&gt;
      &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
    &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="k"&gt;catch&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;err&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
      &lt;span class="n"&gt;label&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;textContent&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="sb"&gt;`Can't connect (${err.message}). Retrying in 5 seconds…`&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
      &lt;span class="nb"&gt;setTimeout&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;start&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="mi"&gt;5000&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
    &lt;span class="p"&gt;}&lt;/span&gt;
  &lt;span class="p"&gt;}&lt;/span&gt;

  &lt;span class="c1"&gt;// The status file says whether anyone is broadcasting and how many people watch.&lt;/span&gt;
  &lt;span class="k"&gt;async&lt;/span&gt; &lt;span class="kd"&gt;function&lt;/span&gt; &lt;span class="nf"&gt;showStatus&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="k"&gt;try&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
      &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="n"&gt;res&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="nb"&gt;fetch&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="sb"&gt;`${HOST}/status/${CHANNEL}.json`&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="n"&gt;cache&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"no-store"&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
      &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="n"&gt;live&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;viewers&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="n"&gt;res&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;json&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
      &lt;span class="k"&gt;if&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;current&lt;/span&gt;&lt;span class="o"&gt;?&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;pc&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;connectionState&lt;/span&gt; &lt;span class="o"&gt;===&lt;/span&gt; &lt;span class="s2"&gt;"connected"&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
        &lt;span class="n"&gt;label&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;textContent&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="n"&gt;live&lt;/span&gt; &lt;span class="o"&gt;?&lt;/span&gt; &lt;span class="sb"&gt;`Live · ${viewers} watching`&lt;/span&gt; &lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"Offline. Back soon."&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
      &lt;span class="p"&gt;}&lt;/span&gt;
    &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="k"&gt;catch&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;&lt;span class="p"&gt;}&lt;/span&gt;
  &lt;span class="p"&gt;}&lt;/span&gt;

  &lt;span class="nf"&gt;addEventListener&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s2"&gt;"pagehide"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="o"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="n"&gt;current&lt;/span&gt; &lt;span class="o"&gt;&amp;amp;&amp;amp;&lt;/span&gt; &lt;span class="nf"&gt;hangUp&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;current&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="nf"&gt;start&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="nb"&gt;setInterval&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;showStatus&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="mi"&gt;10000&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="nf"&gt;showStatus&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="nt"&gt;&amp;lt;/script&amp;gt;&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;What each part does, and why it's there:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;&lt;code&gt;recvonly&lt;/code&gt; transceivers&lt;/strong&gt; tell the server this page only watches. Without them the offer has no media sections and the server has nothing to answer.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;&lt;code&gt;iceGatheringDone&lt;/code&gt;&lt;/strong&gt; waits until the browser has listed its network addresses, so they all go in the one POST. The server's answer already contains its own addresses, so you don't need a second round trip.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;The &lt;code&gt;Location&lt;/code&gt; header&lt;/strong&gt; is the address of &lt;em&gt;this&lt;/em&gt; viewer's session. The server sends a relative path such as &lt;code&gt;/whep/sch_…/8c69bb2f…&lt;/code&gt;, so the code resolves it against &lt;code&gt;HOST&lt;/code&gt;. It's readable from other origins, so this works from any domain.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;&lt;code&gt;DELETE&lt;/code&gt; on &lt;code&gt;pagehide&lt;/code&gt;&lt;/strong&gt; ends the session when the tab closes. &lt;code&gt;keepalive: true&lt;/code&gt; lets the request finish while the page unloads. Skip it and the viewer count stays too high for a while.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Reconnect on &lt;code&gt;failed&lt;/code&gt; only.&lt;/strong&gt; A &lt;code&gt;disconnected&lt;/code&gt; state often heals by itself. When the server really drops a session, Chrome reports &lt;code&gt;disconnected&lt;/code&gt; after about 7 seconds and &lt;code&gt;failed&lt;/code&gt; after about 17. The player then reconnects 2 seconds later.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;The status file&lt;/strong&gt; (&lt;code&gt;/status/&amp;lt;channel&amp;gt;.json&lt;/code&gt;) returns &lt;code&gt;{"live":true,"state":"live","viewers":1,"started_at":"…"}&lt;/code&gt;. It's public, it works from any origin, and it's how the label knows you're offline.&lt;/li&gt;
&lt;/ul&gt;

&lt;h3&gt;
  
  
  You don't need to reconnect when the broadcaster stops
&lt;/h3&gt;

&lt;p&gt;When the broadcast stops, the WebRTC connection &lt;strong&gt;stays up&lt;/strong&gt;: after the channel's failover delay (5 seconds by default) viewers see the server's "This stream is offline" slate, and the status file switches to &lt;code&gt;"live": false&lt;/code&gt;. When you go live again, the same connection picks the video back up. Nobody has to refresh.&lt;/p&gt;

&lt;p&gt;A WHEP request made while you're offline also succeeds (&lt;code&gt;201&lt;/code&gt;) and shows the slate. So you can load the player before the show starts and leave it alone.&lt;/p&gt;

&lt;h2&gt;
  
  
  Check that it really is under a second
&lt;/h2&gt;

&lt;p&gt;To measure delay yourself, broadcast something that shows a clock with milliseconds (a browser tab with a canvas clock works), and put a clock on the viewer page next to the video. Take a screenshot and subtract.&lt;/p&gt;

&lt;p&gt;&lt;a href="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Fbzzdj10y5ve3bi4kedob.png" class="article-body-image-wrapper"&gt;&lt;img src="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Fbzzdj10y5ve3bi4kedob.png" alt="Two players side by side: WebRTC about 1 second behind the viewer's clock, LL-HLS more than 10 seconds behind" width="800" height="202"&gt;&lt;/a&gt;&lt;/p&gt;

&lt;p&gt;On a connection with about 0.4 s round trip to the media server, the numbers look like this:&lt;/p&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Player&lt;/th&gt;
&lt;th&gt;Delay behind live&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;WebRTC (WHEP)&lt;/td&gt;
&lt;td&gt;0.80–0.90 s across five samples&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;LL-HLS (hls.js 1.5.20, low-latency mode)&lt;/td&gt;
&lt;td&gt;about 7 s at start, then 10–20 s after buffer stalls&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Time to first picture, WebRTC&lt;/td&gt;
&lt;td&gt;about 4.7 s from page load&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;p&gt;The WebRTC delay held steady for the whole session. LL-HLS didn't: on a slow link each stall pushes it further behind live. On a faster connection it lands closer to its rated 3–5 seconds.&lt;/p&gt;

&lt;h2&gt;
  
  
  What can go wrong
&lt;/h2&gt;

&lt;p&gt;&lt;strong&gt;WebRTC viewers get a lower quality or LL-HLS instead.&lt;/strong&gt; If you broadcast from an encoder such as OBS or ffmpeg, it's probably sending B-frames, which browsers can't play over WebRTC. The &lt;a href="https://www.hubfly.space/docs/streams/obs-and-encoders/?ref=webrtc-live-streaming-website" rel="noopener noreferrer"&gt;encoder guide&lt;/a&gt; explains how the server handles them and how to turn them off. The browser broadcaster in Step 3 doesn't have this problem.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;&lt;code&gt;TypeError: Failed to fetch&lt;/code&gt; on the WHEP POST, but the status file loads.&lt;/strong&gt; The channel or server has &lt;strong&gt;Allowed websites&lt;/strong&gt; set, and your page's origin isn't on the list. The request is refused before your code can read a status code, so the browser only says "Failed to fetch". Add your page's exact origin, such as &lt;code&gt;https://www.your-domain.com&lt;/code&gt;, or clear the field to allow every site.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;&lt;code&gt;WHEP 401&lt;/code&gt;.&lt;/strong&gt; The channel's access is set to &lt;strong&gt;Signed tokens&lt;/strong&gt;, so every viewer needs a playback token from your backend. The &lt;a href="https://www.hubfly.space/docs/streams/playback-security/?ref=webrtc-live-streaming-website" rel="noopener noreferrer"&gt;playback security guide&lt;/a&gt; shows how to sign one and pass it on the WHEP request. Or switch the channel back to &lt;strong&gt;Public&lt;/strong&gt;.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;It works at home but stays on "Connecting…" on a locked-down office network.&lt;/strong&gt; The media server offers WebRTC on port 8189 (UDP, with TCP as the fallback). A firewall that blocks that port blocks WebRTC. Give those viewers a fallback: after a few failed attempts, play the channel's HLS URL with &lt;a href="https://github.com/video-dev/hls.js" rel="noopener noreferrer"&gt;hls.js&lt;/a&gt; instead.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;New viewers suddenly get a few seconds of delay.&lt;/strong&gt; The server's &lt;strong&gt;WebRTC viewers&lt;/strong&gt; setting (under &lt;strong&gt;Settings&lt;/strong&gt;) caps sub-second viewers at 200 by default, up to 2,000; the docs say viewers beyond it watch over LL-HLS. Also check the server's &lt;strong&gt;speed&lt;/strong&gt;: once viewers use it all up, delivery slows down for everyone.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Video autoplays muted, or doesn't start at all.&lt;/strong&gt; Browsers block autoplay with sound. Keep &lt;code&gt;autoplay muted playsinline&lt;/code&gt; on the &lt;code&gt;&amp;lt;video&amp;gt;&lt;/code&gt; element and show an &lt;strong&gt;Unmute&lt;/strong&gt; button. &lt;code&gt;playsinline&lt;/code&gt; stops iPhones from jumping to full screen.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;The stream key leaked.&lt;/strong&gt; Open &lt;strong&gt;Inputs&lt;/strong&gt;, find &lt;strong&gt;Keys&lt;/strong&gt; and click &lt;strong&gt;Rotate&lt;/strong&gt;; the &lt;a href="https://www.hubfly.space/docs/streams/obs-and-encoders/?ref=webrtc-live-streaming-website" rel="noopener noreferrer"&gt;encoder guide&lt;/a&gt; says encoders using the old key are disconnected. Never put a stream key in front-end code. The browser broadcast in Step 3 keeps it out of your page.&lt;/p&gt;

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

&lt;p&gt;Hubfly space Managed Streams bills three things: the server's &lt;strong&gt;speed&lt;/strong&gt; while it runs, &lt;strong&gt;bandwidth&lt;/strong&gt; sent to viewers, and &lt;strong&gt;processing&lt;/strong&gt; only when it re-encodes. Pass-through channels, like the one above, use no processing. Every account gets the first 25 Mbps of speed, 50 GB of bandwidth and 20 Mbps-hours of processing free each month.&lt;/p&gt;

&lt;p&gt;A worked example: a one-hour show every week, 50 people watching a 2.5 Mbps stream.&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;Bandwidth: 2.5 Mbps × 3,600 s ÷ 8 = 1.125 GB per viewer-hour. 50 viewers × 4 shows = 200 viewer-hours = 225 GB. After the free 50 GB, 175 GB × $0.004 = &lt;strong&gt;$0.70&lt;/strong&gt;.&lt;/li&gt;
&lt;li&gt;Speed: 50 viewers × 2.5 Mbps = 125 Mbps, so raise the server to 130 Mbps for the show. The 105 Mbps above the free 25 cost 105 × $0.000041 = $0.0043 an hour, about &lt;strong&gt;$0.02&lt;/strong&gt; for four one-hour shows. Drop it back to 25 Mbps afterwards (free), or stop the server.&lt;/li&gt;
&lt;li&gt;Processing: pass-through, &lt;strong&gt;$0&lt;/strong&gt;.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;That's about &lt;strong&gt;$0.72 a month&lt;/strong&gt;. If you leave the server at 130 Mbps all month instead, speed alone is about $3.14. Above 250 Mbps (roughly 100 viewers of a 2.5 Mbps stream), Hubfly space asks for a deposit first.&lt;/p&gt;

&lt;h2&gt;
  
  
  FAQ
&lt;/h2&gt;

&lt;p&gt;&lt;strong&gt;How do I embed a low-latency live stream on my website?&lt;/strong&gt;&lt;br&gt;
Create a channel with &lt;em&gt;Ultra-low latency&lt;/em&gt; and paste its embed &lt;code&gt;&amp;lt;iframe&amp;gt;&lt;/code&gt; into your page (Step 4). For your own look, use the WHEP player in Step 5.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;What are WHIP and WHEP?&lt;/strong&gt;&lt;br&gt;
Two small HTTP protocols for WebRTC. WHIP sends video in, WHEP pulls it out. Each is one POST with an SDP offer, one SDP answer back, and a session URL you DELETE when you're done. WHIP is an IETF standard (RFC 9725); WHEP is still an Internet-Draft, but servers and players already use it.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Can I broadcast from OBS instead of a browser?&lt;/strong&gt;&lt;br&gt;
Yes. OBS Studio added WHIP output in version 30, and the Hubfly space &lt;a href="https://www.hubfly.space/docs/streams/obs-and-encoders/?ref=webrtc-live-streaming-website" rel="noopener noreferrer"&gt;encoder guide&lt;/a&gt; lists the settings. Turn B-frames off for WebRTC viewers.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;How much latency does WebRTC streaming have?&lt;/strong&gt;&lt;br&gt;
Under a second in practice. In the table above it was 0.8–0.9 s from broadcaster to viewer with a 0.4 s network round trip, against 3–5 s for LL-HLS at best and 15–25 s for standard HLS.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;How many viewers can watch over WebRTC?&lt;/strong&gt;&lt;br&gt;
200 at once per server by default, and you can raise the limit to 2,000. Above it, the docs say extra viewers get LL-HLS. For bigger audiences, check the server's speed too.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Why is my WebRTC stream black when HLS works?&lt;/strong&gt;&lt;br&gt;
Usually B-frames from an encoder, or a network that blocks port 8189. Check the input's health panel and try another network.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Do I need my own TURN server?&lt;/strong&gt;&lt;br&gt;
Not to get started: the media server has a public address that browsers connect to directly. For viewers on networks that block port 8189, an HLS fallback is simpler than running TURN.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Is WebRTC or LL-HLS better for my site?&lt;/strong&gt;&lt;br&gt;
WebRTC when viewers interact with the stream: auctions, Q&amp;amp;A, classes, sports betting, game shows. LL-HLS or HLS when nobody notices a few seconds and you want the widest device support and CDN-friendly caching.&lt;/p&gt;

&lt;h2&gt;
  
  
  Go further on Hubfly space
&lt;/h2&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;Restream the same broadcast to YouTube and Twitch&lt;/strong&gt; while your site plays the sub-second version: &lt;a href="https://www.hubfly.space/docs/streams/restreaming/?ref=webrtc-live-streaming-website" rel="noopener noreferrer"&gt;Restreaming&lt;/a&gt;.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Make the stream members-only&lt;/strong&gt; with short-lived playback tokens signed by your backend: &lt;a href="https://www.hubfly.space/docs/streams/playback-security/?ref=webrtc-live-streaming-website" rel="noopener noreferrer"&gt;Playback security&lt;/a&gt;.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Record every show to Hubfly space Storage&lt;/strong&gt; and turn highlights into clips: &lt;a href="https://www.hubfly.space/docs/streams/recording-and-clips/?ref=webrtc-live-streaming-website" rel="noopener noreferrer"&gt;Recording and clips&lt;/a&gt;.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;Related reading: &lt;a href="https://blog.hubfly.space/live-video-streaming-costs?utm_source=devto&amp;amp;utm_medium=crosspost&amp;amp;utm_campaign=webrtc-live-streaming-website" rel="noopener noreferrer"&gt;Live video costs in 2026: Mux, Cloudflare, IVS, Hubfly space&lt;/a&gt; compares what an hour of live video costs on each platform.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;&lt;a href="https://www.hubfly.space/?ref=webrtc-live-streaming-website" rel="noopener noreferrer"&gt;Try it on Hubfly space&lt;/a&gt;&lt;/strong&gt;: create a 25 Mbps stream server and have sub-second video on your site in about ten minutes.&lt;/p&gt;




&lt;p&gt;&lt;em&gt;By Octave · drafted with AI, tested on Hubfly · Last updated 11 November 2026&lt;/em&gt;&lt;/p&gt;

</description>
      <category>webrtc</category>
      <category>javascript</category>
      <category>streaming</category>
      <category>webdev</category>
    </item>
    <item>
      <title>How to run a cron job in a Docker container (with logs)</title>
      <dc:creator>octave Nkurunziza</dc:creator>
      <pubDate>Tue, 10 Nov 2026 16:17:42 +0000</pubDate>
      <link>https://dev.to/octave_nkurunziza_afb0512/how-to-run-a-cron-job-in-a-docker-container-with-logs-228e</link>
      <guid>https://dev.to/octave_nkurunziza_afb0512/how-to-run-a-cron-job-in-a-docker-container-with-logs-228e</guid>
      <description>&lt;p&gt;&lt;em&gt;Last updated: 5 November 2026 · Applies to Debian-based images (python:3.13-slim, Debian 13 trixie) with Debian cron 3.0pl1, Alpine 3.24, supercronic 0.2.51, Docker Compose v2+&lt;/em&gt;&lt;/p&gt;

&lt;p&gt;You want a script to run every night, or every five minutes, next to your app in Docker. This guide shows how to run a cron job in a Docker container so that it actually fires, sees the same environment variables as your app, prints to &lt;code&gt;docker logs&lt;/code&gt;, never runs twice at once, and stops cleanly on &lt;code&gt;docker stop&lt;/code&gt;.&lt;/p&gt;

&lt;p&gt;Why it matters: cron inside a container fails silently. No error, no log line, the job just never runs, and you find out a week later when the backups are missing. Many popular guides stop at &lt;code&gt;CMD cron &amp;amp;&amp;amp; tail -f&lt;/code&gt;, which hides exactly the problems that bite in production.&lt;/p&gt;

&lt;p&gt;&lt;a href="https://hubfly.space/?ref=cron-job-in-docker-container" rel="noopener noreferrer"&gt;&lt;strong&gt;Try it on Hubfly space&lt;/strong&gt;&lt;/a&gt;: deploy the Compose file below as a two-container stack.&lt;/p&gt;

&lt;h2&gt;
  
  
  Run a cron job in a Docker container: the short answer
&lt;/h2&gt;

&lt;p&gt;Run cron as &lt;strong&gt;its own service&lt;/strong&gt; built from the &lt;strong&gt;same image&lt;/strong&gt; as your app. Start it with &lt;code&gt;cron -f&lt;/code&gt;, save the container's environment to a file at startup, send job output to &lt;code&gt;/proc/1/fd/1&lt;/code&gt;, wrap each job in &lt;code&gt;flock&lt;/code&gt;, and set &lt;code&gt;init: true&lt;/code&gt; so &lt;code&gt;docker stop&lt;/code&gt; works. Everything below is copy-paste ready.&lt;/p&gt;

&lt;h2&gt;
  
  
  Pick the right approach
&lt;/h2&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Approach&lt;/th&gt;
&lt;th&gt;Good for&lt;/th&gt;
&lt;th&gt;Watch out for&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;Host crontab + &lt;code&gt;docker exec&lt;/code&gt;
&lt;/td&gt;
&lt;td&gt;One server you control&lt;/td&gt;
&lt;td&gt;Breaks on any PaaS or Kubernetes, lives outside your repo&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Cron inside the app container&lt;/td&gt;
&lt;td&gt;Quick hacks&lt;/td&gt;
&lt;td&gt;Two processes in one container: if cron dies, nobody notices&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;strong&gt;Separate cron container, same image&lt;/strong&gt;&lt;/td&gt;
&lt;td&gt;Most apps (this guide)&lt;/td&gt;
&lt;td&gt;Must run exactly one copy&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;supercronic instead of cron&lt;/td&gt;
&lt;td&gt;New images, minimal setup&lt;/td&gt;
&lt;td&gt;Extra binary to download and pin&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Scheduler in your app (Celery beat, node-cron, APScheduler)&lt;/td&gt;
&lt;td&gt;Apps that already run a worker&lt;/td&gt;
&lt;td&gt;Ties scheduling to app code and its deploys&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;p&gt;The separate container wins for most teams: the schedule lives in Git, it restarts on its own, and its logs sit right next to your app's.&lt;/p&gt;

&lt;h2&gt;
  
  
  Step 1: Lay out the files
&lt;/h2&gt;



&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;shop-api/
├── app/                  # your application code
├── jobs/
│   └── cleanup_sessions.py
├── docker/
│   ├── crontab
│   └── cron-entrypoint.sh
├── Dockerfile
└── compose.yaml
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;A stand-in job so you can see it work. Replace it with your real script:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight python"&gt;&lt;code&gt;&lt;span class="c1"&gt;# jobs/cleanup_sessions.py&lt;/span&gt;
&lt;span class="k"&gt;import&lt;/span&gt; &lt;span class="n"&gt;os&lt;/span&gt;
&lt;span class="k"&gt;from&lt;/span&gt; &lt;span class="n"&gt;datetime&lt;/span&gt; &lt;span class="k"&gt;import&lt;/span&gt; &lt;span class="n"&gt;datetime&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;timezone&lt;/span&gt;

&lt;span class="n"&gt;db&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="n"&gt;os&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;environ&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;get&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s2"&gt;"DATABASE_URL"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="s2"&gt;"&amp;lt;missing&amp;gt;"&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
&lt;span class="k"&gt;print&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;f&lt;/span&gt;&lt;span class="s2"&gt;"{datetime.now(timezone.utc):%Y-%m-%d %H:%M:%S} cleanup_sessions: connecting to {db.split('@')[-1]}"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;flush&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="kc"&gt;True&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;h2&gt;
  
  
  Step 2: Write the crontab for a Docker container
&lt;/h2&gt;

&lt;p&gt;Why: the crontab format inside &lt;code&gt;/etc/cron.d/&lt;/code&gt; has strict rules, and cron &lt;strong&gt;ignores a file that breaks them without printing anything&lt;/strong&gt;.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;# docker/crontab  (installed as /etc/cron.d/shop-jobs)
SHELL=/bin/sh

# Every 5 minutes: clean up expired sessions
*/5 * * * * root flock -n /tmp/cleanup_sessions.lock /usr/local/bin/run-job python /app/jobs/cleanup_sessions.py &amp;gt;&amp;gt; /proc/1/fd/1 2&amp;gt;&amp;gt; /proc/1/fd/2

# Every night at 02:30: date-stamped log line (note the escaped %)
30 2 * * * root echo "nightly run $(date +\%F)" &amp;gt;&amp;gt; /proc/1/fd/1 2&amp;gt;&amp;amp;1

&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Five rules decide whether these lines ever run:&lt;/p&gt;

&lt;ol&gt;
&lt;li&gt;
&lt;strong&gt;A user column.&lt;/strong&gt; Files in &lt;code&gt;/etc/cron.d/&lt;/code&gt; need a user (&lt;code&gt;root&lt;/code&gt; above) between the schedule and the command. A line without it is skipped.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;The file name has no dot.&lt;/strong&gt; Debian cron ignores &lt;code&gt;/etc/cron.d/&lt;/code&gt; files whose names contain a dot. &lt;code&gt;shop-jobs&lt;/code&gt; runs; &lt;code&gt;shop-jobs.cron&lt;/code&gt; never does.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;A trailing newline.&lt;/strong&gt; If the last line doesn't end with a newline, cron drops it. Keep an empty line at the end of the file.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Permissions 0644, owned by root.&lt;/strong&gt; Cron rejects files that the group or others can write (for example 0664).&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Escape every &lt;code&gt;%&lt;/code&gt; as &lt;code&gt;\%&lt;/code&gt;.&lt;/strong&gt; In a crontab, &lt;code&gt;%&lt;/code&gt; means "newline, and send the rest to stdin". &lt;code&gt;date +%F&lt;/code&gt; silently breaks the whole command.&lt;/li&gt;
&lt;/ol&gt;

&lt;p&gt;Two more habits that save hours:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;Use absolute paths.&lt;/strong&gt; Cron's default &lt;code&gt;PATH&lt;/code&gt; is just &lt;code&gt;/usr/bin:/bin&lt;/code&gt;, so &lt;code&gt;python&lt;/code&gt; from &lt;code&gt;/usr/local/bin&lt;/code&gt; is not found. The &lt;code&gt;run-job&lt;/code&gt; wrapper in Step 3 fixes this, but absolute paths make the crontab readable on its own.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;&lt;code&gt;flock -n&lt;/code&gt; stops overlapping runs.&lt;/strong&gt; If the previous run still holds the lock, the new one exits at once instead of piling up.&lt;/li&gt;
&lt;/ul&gt;

&lt;h2&gt;
  
  
  Step 3: Pass environment variables to cron jobs
&lt;/h2&gt;

&lt;p&gt;Why: cron starts every job with an almost empty environment. Your &lt;code&gt;DATABASE_URL&lt;/code&gt;, API keys and &lt;code&gt;TZ&lt;/code&gt;, set with &lt;code&gt;environment:&lt;/code&gt; or &lt;code&gt;-e&lt;/code&gt;, are &lt;strong&gt;not visible&lt;/strong&gt; to the job. This is the number one reason a cron job "works when I run it by hand".&lt;/p&gt;

&lt;p&gt;Save the environment once at container start, then load it before each job:&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="c"&gt;# docker/cron-entrypoint.sh&lt;/span&gt;
&lt;span class="nb"&gt;set&lt;/span&gt; -eu

&lt;span class="c"&gt;# Save the container's environment, safely quoted, readable only by root&lt;/span&gt;
&lt;span class="kd"&gt;export&lt;/span&gt; -p &lt;span class="o"&gt;&amp;gt;&lt;/span&gt; /run/cron.env
chmod 600 /run/cron.env

&lt;span class="nb"&gt;exec&lt;/span&gt; cron -f
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;





&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;&lt;span class="c"&gt;#!/bin/sh&lt;/span&gt;
&lt;span class="c"&gt;# /usr/local/bin/run-job (created in the Dockerfile)&lt;/span&gt;
. /run/cron.env
&lt;span class="nb"&gt;exec&lt;/span&gt; &lt;span class="s2"&gt;"$@"&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;&lt;code&gt;export -p&lt;/code&gt; writes each variable as &lt;code&gt;export NAME='value'&lt;/code&gt; with proper quoting, so passwords with spaces, quotes or &lt;code&gt;@&lt;/code&gt; survive. That's safer than the popular &lt;code&gt;env &amp;gt;&amp;gt; /etc/environment&lt;/code&gt;, which breaks on quotes and appends duplicates on every restart. Because the snapshot also restores the container's &lt;code&gt;PATH&lt;/code&gt;, &lt;code&gt;python&lt;/code&gt; resolves inside jobs.&lt;/p&gt;

&lt;p&gt;Keep the file at &lt;strong&gt;mode 600&lt;/strong&gt;: it holds your secrets.&lt;/p&gt;

&lt;h2&gt;
  
  
  Step 4: The Dockerfile
&lt;/h2&gt;



&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight docker"&gt;&lt;code&gt;&lt;span class="c"&gt;# Dockerfile&lt;/span&gt;
&lt;span class="k"&gt;FROM&lt;/span&gt; python:3.13-slim

&lt;span class="k"&gt;RUN&lt;/span&gt; apt-get update \
 &lt;span class="o"&gt;&amp;amp;&amp;amp;&lt;/span&gt; apt-get install -y --no-install-recommends cron tzdata curl ca-certificates \
 &lt;span class="o"&gt;&amp;amp;&amp;amp;&lt;/span&gt; rm -rf /var/lib/apt/lists/*

&lt;span class="k"&gt;WORKDIR&lt;/span&gt; /app
&lt;span class="k"&gt;COPY&lt;/span&gt; requirements.txt .
&lt;span class="k"&gt;RUN&lt;/span&gt; pip install --no-cache-dir -r requirements.txt
&lt;span class="k"&gt;COPY&lt;/span&gt; . .

&lt;span class="c"&gt;# Cron files: no dot in the name, 0644, root-owned&lt;/span&gt;
&lt;span class="k"&gt;COPY&lt;/span&gt; docker/crontab /etc/cron.d/shop-jobs
&lt;span class="k"&gt;RUN&lt;/span&gt; chmod 0644 /etc/cron.d/shop-jobs \
 &lt;span class="o"&gt;&amp;amp;&amp;amp;&lt;/span&gt; &lt;span class="nb"&gt;printf&lt;/span&gt; &lt;span class="s1"&gt;'#!/bin/sh\n. /run/cron.env\nexec "$@"\n'&lt;/span&gt; &lt;span class="o"&gt;&amp;gt;&lt;/span&gt; /usr/local/bin/run-job \
 &lt;span class="o"&gt;&amp;amp;&amp;amp;&lt;/span&gt; chmod 0755 /usr/local/bin/run-job

&lt;span class="k"&gt;COPY&lt;/span&gt; docker/cron-entrypoint.sh /usr/local/bin/cron-entrypoint
&lt;span class="k"&gt;RUN&lt;/span&gt; chmod 0755 /usr/local/bin/cron-entrypoint

&lt;span class="c"&gt;# The app is the default; the cron service overrides this&lt;/span&gt;
&lt;span class="k"&gt;CMD&lt;/span&gt; &lt;span class="o"&gt;[&lt;/span&gt;&lt;span class="s2"&gt;"gunicorn"&lt;/span&gt;, &lt;span class="s2"&gt;"app.main:app"&lt;/span&gt;, &lt;span class="s2"&gt;"--bind"&lt;/span&gt;, &lt;span class="s2"&gt;"0.0.0.0:8000"&lt;/span&gt;&lt;span class="o"&gt;]&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;One image, two jobs: the web container runs &lt;code&gt;CMD&lt;/code&gt;, the cron container runs the entrypoint. Both always ship the same code. Replace the &lt;code&gt;requirements.txt&lt;/code&gt; lines and &lt;code&gt;CMD&lt;/code&gt; with your app's own install and start commands. &lt;code&gt;curl&lt;/code&gt; is there for the heartbeat ping further down.&lt;/p&gt;

&lt;h2&gt;
  
  
  Step 5: Add a cron service to Docker Compose
&lt;/h2&gt;



&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight yaml"&gt;&lt;code&gt;&lt;span class="c1"&gt;# compose.yaml
&lt;/span&gt;&lt;span class="na"&gt;services&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
  &lt;span class="na"&gt;web&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
    &lt;span class="na"&gt;build&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s"&gt;.&lt;/span&gt;
    &lt;span class="na"&gt;environment&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
      &lt;span class="na"&gt;DATABASE_URL&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s"&gt;${DATABASE_URL}&lt;/span&gt;
      &lt;span class="na"&gt;TZ&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s"&gt;Africa/Kigali&lt;/span&gt;
    &lt;span class="na"&gt;ports&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
      &lt;span class="p"&gt;-&lt;/span&gt; &lt;span class="s2"&gt;"8000:8000"&lt;/span&gt;
    &lt;span class="na"&gt;restart&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s"&gt;unless-stopped&lt;/span&gt;

  &lt;span class="na"&gt;cron&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
    &lt;span class="na"&gt;build&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s"&gt;.&lt;/span&gt;
    &lt;span class="na"&gt;command&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="s2"&gt;"/usr/local/bin/cron-entrypoint"&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;
    &lt;span class="na"&gt;init&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kc"&gt;true&lt;/span&gt;
    &lt;span class="na"&gt;environment&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
      &lt;span class="na"&gt;DATABASE_URL&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s"&gt;${DATABASE_URL}&lt;/span&gt;
      &lt;span class="na"&gt;TZ&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s"&gt;Africa/Kigali&lt;/span&gt;
    &lt;span class="na"&gt;stop_grace_period&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s"&gt;30s&lt;/span&gt;
    &lt;span class="na"&gt;restart&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s"&gt;unless-stopped&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;What each setting does:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;&lt;code&gt;init: true&lt;/code&gt;&lt;/strong&gt; puts a tiny init process in front of cron. Without it, cron is process 1, and process 1 ignores &lt;code&gt;SIGTERM&lt;/code&gt; because cron sets no handler for it. Every &lt;code&gt;docker stop&lt;/code&gt; then waits the full grace period and ends with a &lt;code&gt;SIGKILL&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;&lt;code&gt;TZ&lt;/code&gt;&lt;/strong&gt; sets the time zone for the schedule. Cron reads it at startup, so &lt;code&gt;30 2 * * *&lt;/code&gt; means 02:30 Kigali time here. The image needs &lt;code&gt;tzdata&lt;/code&gt;, which the Dockerfile installs. Leave &lt;code&gt;TZ&lt;/code&gt; out and schedules run in UTC.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;&lt;code&gt;stop_grace_period: 30s&lt;/code&gt;&lt;/strong&gt; caps how long Docker waits before it force-kills the container. A job that is mid-run is still interrupted, so make every job safe to re-run.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;No &lt;code&gt;ports&lt;/code&gt;&lt;/strong&gt; on the cron service. It serves nothing.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;Put your secrets in a &lt;code&gt;.env&lt;/code&gt; file next to &lt;code&gt;compose.yaml&lt;/code&gt; (and in &lt;code&gt;.gitignore&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;DATABASE_URL=postgres://shop:change-me@orders-db:5432/shop
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Add a &lt;code&gt;.dockerignore&lt;/code&gt; so &lt;code&gt;COPY . .&lt;/code&gt; never bakes that file into the image:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;# .dockerignore
.env
.git
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;h2&gt;
  
  
  Step 6: Start it and check the logs
&lt;/h2&gt;



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

&lt;/div&gt;



&lt;p&gt;Within five minutes you should see:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;cron-1  | 2026-11-05 09:35:01 cleanup_sessions: connecting to orders-db:5432/shop
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Run a job by hand with the same environment cron uses:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;docker compose &lt;span class="nb"&gt;exec&lt;/span&gt; cron run-job python /app/jobs/cleanup_sessions.py
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Check that cron loaded your file and sees the right time zone:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;docker compose &lt;span class="nb"&gt;exec&lt;/span&gt; cron ls -l /etc/cron.d/
docker compose &lt;span class="nb"&gt;exec&lt;/span&gt; cron date
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Why &lt;code&gt;/proc/1/fd/1&lt;/code&gt;: Docker collects only what process 1 writes to stdout and stderr. Cron's own children don't write there, so their output vanishes (cron tries to email it, and a container has no mail server). Appending to process 1's stdout puts each job's output in &lt;code&gt;docker logs&lt;/code&gt;, with no log file filling up the disk. Use &lt;code&gt;&amp;gt;&amp;gt;&lt;/code&gt;, not &lt;code&gt;&amp;gt;&lt;/code&gt;: if stdout is ever a file, &lt;code&gt;&amp;gt;&lt;/code&gt; truncates it on every run.&lt;/p&gt;

&lt;h2&gt;
  
  
  Alpine images: use busybox crond
&lt;/h2&gt;

&lt;p&gt;On Alpine, &lt;code&gt;crond&lt;/code&gt; comes from BusyBox and behaves differently:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;The crontab goes in &lt;strong&gt;&lt;code&gt;/etc/crontabs/root&lt;/code&gt;&lt;/strong&gt; with &lt;strong&gt;no user column&lt;/strong&gt;.&lt;/li&gt;
&lt;li&gt;It &lt;strong&gt;keeps the container's environment&lt;/strong&gt;, so you can skip the snapshot step.&lt;/li&gt;
&lt;li&gt;Start it in the foreground with logging: &lt;code&gt;crond -f -l 2&lt;/code&gt;.
&lt;/li&gt;
&lt;/ul&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;# docker/crontab-alpine  (installed as /etc/crontabs/root; keep the empty last line)
*/5 * * * * /app/jobs/cleanup.sh &amp;gt;&amp;gt; /proc/1/fd/1 2&amp;gt;&amp;gt; /proc/1/fd/2

&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;





&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight docker"&gt;&lt;code&gt;&lt;span class="k"&gt;FROM&lt;/span&gt; alpine:3.24
&lt;span class="k"&gt;RUN&lt;/span&gt; apk add --no-cache tzdata
&lt;span class="k"&gt;COPY&lt;/span&gt; jobs/ /app/jobs/
&lt;span class="k"&gt;COPY&lt;/span&gt; docker/crontab-alpine /etc/crontabs/root
&lt;span class="k"&gt;CMD&lt;/span&gt; &lt;span class="o"&gt;[&lt;/span&gt;&lt;span class="s2"&gt;"crond"&lt;/span&gt;, &lt;span class="s2"&gt;"-f"&lt;/span&gt;, &lt;span class="s2"&gt;"-l"&lt;/span&gt;, &lt;span class="s2"&gt;"2"&lt;/span&gt;&lt;span class="o"&gt;]&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;A matching job script (inside a script, &lt;code&gt;%&lt;/code&gt; needs no escaping):&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="c"&gt;# jobs/cleanup.sh&lt;/span&gt;
&lt;span class="nb"&gt;set&lt;/span&gt; -eu
&lt;span class="nb"&gt;echo&lt;/span&gt; &lt;span class="s2"&gt;"$(date -u '+%F %T') cleanup: ok"&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Make it executable (&lt;code&gt;chmod +x jobs/cleanup.sh&lt;/code&gt;) before you build. BusyBox crond has no built-in overlap protection; if a job can run longer than its interval, use supercronic (below).&lt;/p&gt;

&lt;p&gt;Keep &lt;code&gt;init: true&lt;/code&gt; in Compose here too.&lt;/p&gt;

&lt;h2&gt;
  
  
  Option: supercronic, a cron built for containers
&lt;/h2&gt;

&lt;p&gt;&lt;a href="https://github.com/aptible/supercronic" rel="noopener noreferrer"&gt;supercronic&lt;/a&gt; runs a normal crontab (no user column) in the foreground, keeps the environment, writes each job's output to the container's log stream, waits for a job to finish before starting the same job again, and shuts down gracefully on &lt;code&gt;SIGTERM&lt;/code&gt;. Install it with the checksum its release page publishes (version &lt;strong&gt;0.2.51&lt;/strong&gt;, amd64):&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight docker"&gt;&lt;code&gt;&lt;span class="k"&gt;ENV&lt;/span&gt; &lt;span class="nv"&gt;SUPERCRONIC_URL&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;https://github.com/aptible/supercronic/releases/download/v0.2.51/supercronic-linux-amd64 \
    &lt;span class="nv"&gt;SUPERCRONIC_SHA1SUM&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;1692066e350a88ff4d7d6474fe3c7a6c41ec5e89 \
    &lt;span class="nv"&gt;SUPERCRONIC&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;supercronic-linux-amd64

&lt;span class="k"&gt;RUN&lt;/span&gt; apt-get update &lt;span class="o"&gt;&amp;amp;&amp;amp;&lt;/span&gt; apt-get install -y --no-install-recommends curl ca-certificates \
 &lt;span class="o"&gt;&amp;amp;&amp;amp;&lt;/span&gt; curl -fsSLO &lt;span class="s2"&gt;"$SUPERCRONIC_URL"&lt;/span&gt; \
 &lt;span class="o"&gt;&amp;amp;&amp;amp;&lt;/span&gt; &lt;span class="nb"&gt;echo&lt;/span&gt; &lt;span class="s2"&gt;"${SUPERCRONIC_SHA1SUM}  ${SUPERCRONIC}"&lt;/span&gt; &lt;span class="o"&gt;|&lt;/span&gt; sha1sum -c - \
 &lt;span class="o"&gt;&amp;amp;&amp;amp;&lt;/span&gt; chmod +x &lt;span class="s2"&gt;"$SUPERCRONIC"&lt;/span&gt; \
 &lt;span class="o"&gt;&amp;amp;&amp;amp;&lt;/span&gt; mv &lt;span class="s2"&gt;"$SUPERCRONIC"&lt;/span&gt; /usr/local/bin/supercronic \
 &lt;span class="o"&gt;&amp;amp;&amp;amp;&lt;/span&gt; rm -rf /var/lib/apt/lists/*

&lt;span class="k"&gt;COPY&lt;/span&gt; docker/crontab-supercronic /app/crontab
&lt;span class="k"&gt;CMD&lt;/span&gt; &lt;span class="o"&gt;[&lt;/span&gt;&lt;span class="s2"&gt;"supercronic"&lt;/span&gt;, &lt;span class="s2"&gt;"/app/crontab"&lt;/span&gt;&lt;span class="o"&gt;]&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;For ARM servers, use the &lt;code&gt;supercronic-linux-arm64&lt;/code&gt; asset and its checksum from the &lt;a href="https://github.com/aptible/supercronic/releases/latest" rel="noopener noreferrer"&gt;same release page&lt;/a&gt;. Run &lt;code&gt;supercronic -test /app/crontab&lt;/code&gt; to check the syntax before you ship.&lt;/p&gt;

&lt;h2&gt;
  
  
  Know when a job didn't run
&lt;/h2&gt;

&lt;p&gt;A cron job that silently stops is worse than one that fails loudly. Ping a dead man's switch (any uptime or heartbeat monitor) only after success:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;0 3 * * * root flock -n /tmp/backup.lock /usr/local/bin/run-job sh -c 'python /app/jobs/backup.py &amp;amp;&amp;amp; curl -fsS -m 10 "$HEARTBEAT_URL"' &amp;gt;&amp;gt; /proc/1/fd/1 2&amp;gt;&amp;gt; /proc/1/fd/2
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;If the ping doesn't arrive on time, the monitor alerts you. Set &lt;code&gt;HEARTBEAT_URL&lt;/code&gt; in the cron service's &lt;code&gt;environment&lt;/code&gt;.&lt;/p&gt;

&lt;h2&gt;
  
  
  Run the cron container on Hubfly space
&lt;/h2&gt;

&lt;p&gt;Deploy &lt;code&gt;web&lt;/code&gt; and &lt;code&gt;cron&lt;/code&gt; on Hubfly space as two containers from the same image or repository: &lt;code&gt;web&lt;/code&gt; keeps the default command, and &lt;code&gt;cron&lt;/code&gt; runs &lt;code&gt;/usr/local/bin/cron-entrypoint&lt;/code&gt; with the same environment variables. Import the Compose file with the Stack Composer, and check that the &lt;code&gt;cron&lt;/code&gt; service keeps that command after import. Two settings matter for a scheduler:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;Keep it always on.&lt;/strong&gt; Shared-tier containers auto-sleep when idle, and a sleeping container runs no jobs. Put the &lt;code&gt;cron&lt;/code&gt; container on the &lt;strong&gt;Dedicated&lt;/strong&gt; tier with &lt;strong&gt;24×7 on&lt;/strong&gt; and &lt;strong&gt;Auto Sleep off&lt;/strong&gt;.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Run exactly one copy.&lt;/strong&gt; Don't add replicas to the &lt;code&gt;cron&lt;/code&gt; container: each replica runs the full schedule, so every job fires once per copy. Scale &lt;code&gt;web&lt;/code&gt; instead.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;Job output shows up in the container's &lt;strong&gt;Logs&lt;/strong&gt; tab, with stderr lines marked &lt;strong&gt;ERR&lt;/strong&gt;. The smallest always-on scheduler (0.5 vCPU, 256 MB, 1 GB disk) costs about &lt;strong&gt;$1.84 a month&lt;/strong&gt;: 0.5 × $0.004 × 730 h = $1.46 for CPU, 0.25 × $0.002 × 730 h = $0.37 for memory, and about $0.01 for storage.&lt;/p&gt;

&lt;h2&gt;
  
  
  What can go wrong
&lt;/h2&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Symptom&lt;/th&gt;
&lt;th&gt;Cause&lt;/th&gt;
&lt;th&gt;Fix&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;Job never runs, no error anywhere&lt;/td&gt;
&lt;td&gt;File name has a dot, last line has no newline, missing user column, or file mode isn't 0644&lt;/td&gt;
&lt;td&gt;Rename to &lt;code&gt;shop-jobs&lt;/code&gt;, add an empty last line, add &lt;code&gt;root&lt;/code&gt;, &lt;code&gt;chmod 0644&lt;/code&gt;
&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Works by hand, fails in cron&lt;/td&gt;
&lt;td&gt;Cron strips environment variables and &lt;code&gt;PATH&lt;/code&gt;
&lt;/td&gt;
&lt;td&gt;Use the &lt;code&gt;export -p&lt;/code&gt; snapshot and &lt;code&gt;run-job&lt;/code&gt; wrapper&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;python: not found&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Cron's &lt;code&gt;PATH&lt;/code&gt; is &lt;code&gt;/usr/bin:/bin&lt;/code&gt;
&lt;/td&gt;
&lt;td&gt;Absolute paths, or the &lt;code&gt;run-job&lt;/code&gt; wrapper&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Command with &lt;code&gt;date +%F&lt;/code&gt; does nothing&lt;/td&gt;
&lt;td&gt;
&lt;code&gt;%&lt;/code&gt; is special in crontabs&lt;/td&gt;
&lt;td&gt;Write &lt;code&gt;\%&lt;/code&gt;
&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;
&lt;code&gt;docker logs&lt;/code&gt; is empty&lt;/td&gt;
&lt;td&gt;Job output isn't sent to process 1&lt;/td&gt;
&lt;td&gt;Append &lt;code&gt;&amp;gt;&amp;gt; /proc/1/fd/1 2&amp;gt;&amp;gt; /proc/1/fd/2&lt;/code&gt;
&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;
&lt;code&gt;docker stop&lt;/code&gt; hangs for the whole grace period, then kills&lt;/td&gt;
&lt;td&gt;Cron is process 1 and ignores &lt;code&gt;SIGTERM&lt;/code&gt;
&lt;/td&gt;
&lt;td&gt;
&lt;code&gt;init: true&lt;/code&gt; (or &lt;code&gt;docker run --init&lt;/code&gt;)&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Jobs run at the wrong hour&lt;/td&gt;
&lt;td&gt;Container runs in UTC&lt;/td&gt;
&lt;td&gt;Set &lt;code&gt;TZ&lt;/code&gt; and install &lt;code&gt;tzdata&lt;/code&gt;
&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Job runs twice&lt;/td&gt;
&lt;td&gt;Two cron containers or replicas, or a slow run overlapping the next&lt;/td&gt;
&lt;td&gt;One scheduler only, plus &lt;code&gt;flock -n&lt;/code&gt;
&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;h2&gt;
  
  
  FAQ
&lt;/h2&gt;

&lt;h3&gt;
  
  
  Why is my cron job not running in Docker?
&lt;/h3&gt;

&lt;p&gt;Usually because cron ignored the file: a dot in the name under &lt;code&gt;/etc/cron.d/&lt;/code&gt;, no newline at the end, no user column, or permissions other than 0644. The other common cause is cron not running at all: the container's command must be &lt;code&gt;cron -f&lt;/code&gt;, not &lt;code&gt;cron&lt;/code&gt; (which goes to the background, so the container exits).&lt;/p&gt;

&lt;h3&gt;
  
  
  How do I pass environment variables to a cron job in Docker?
&lt;/h3&gt;

&lt;p&gt;Cron doesn't pass them on. Save them at startup with &lt;code&gt;export -p &amp;gt; /run/cron.env&lt;/code&gt; and source that file before each job, as in Step 3. Or use BusyBox crond or supercronic, which keep the environment.&lt;/p&gt;

&lt;h3&gt;
  
  
  How do I see cron job output with docker logs?
&lt;/h3&gt;

&lt;p&gt;Append the job's output to process 1: &lt;code&gt;&amp;gt;&amp;gt; /proc/1/fd/1 2&amp;gt;&amp;gt; /proc/1/fd/2&lt;/code&gt;. Docker only captures process 1's stdout and stderr.&lt;/p&gt;

&lt;h3&gt;
  
  
  Should cron run in the same container as my app?
&lt;/h3&gt;

&lt;p&gt;No. One process per container keeps restarts and logs simple. Run a second service from the same image with a different command, as in Step 5.&lt;/p&gt;

&lt;h3&gt;
  
  
  How do I set the time zone for cron in a Docker container?
&lt;/h3&gt;

&lt;p&gt;Set &lt;code&gt;TZ&lt;/code&gt; (for example &lt;code&gt;TZ=Europe/Berlin&lt;/code&gt;) on the cron container and install &lt;code&gt;tzdata&lt;/code&gt; in the image. Cron reads the time zone at startup, so restart the container after changing it.&lt;/p&gt;

&lt;h3&gt;
  
  
  How do I stop a cron job from running twice at the same time?
&lt;/h3&gt;

&lt;p&gt;Wrap it in &lt;code&gt;flock -n /tmp/job-name.lock&lt;/code&gt;. If the previous run still holds the lock, the new run exits at once. supercronic does this by default.&lt;/p&gt;

&lt;h3&gt;
  
  
  Can I use docker exec from the host's crontab instead?
&lt;/h3&gt;

&lt;p&gt;Yes, on a single server: &lt;code&gt;*/5 * * * * cd /srv/shop-api &amp;amp;&amp;amp; docker compose exec -T web python /app/jobs/cleanup_sessions.py&lt;/code&gt;. Using the Compose service name survives container recreation, but the schedule still lives outside your repo and doesn't move with your app to another host or platform.&lt;/p&gt;

&lt;h3&gt;
  
  
  Is supercronic better than cron in Docker?
&lt;/h3&gt;

&lt;p&gt;For new images, it's simpler: no user column, environment kept, job output in &lt;code&gt;docker logs&lt;/code&gt;, no overlap. Debian cron is fine when you already use a Debian-based image and follow the rules above.&lt;/p&gt;

&lt;h2&gt;
  
  
  Related guides
&lt;/h2&gt;

&lt;ul&gt;
&lt;li&gt;&lt;a href="https://blog.hubfly.space/docker-health-checks-postgres-redis?utm_source=devto&amp;amp;utm_medium=crosspost&amp;amp;utm_campaign=cron-job-in-docker-container" rel="noopener noreferrer"&gt;Docker health checks that catch real problems&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href="https://blog.hubfly.space/docker-compose-migration-job-service-completed-successfully?utm_source=devto&amp;amp;utm_medium=crosspost&amp;amp;utm_campaign=cron-job-in-docker-container" rel="noopener noreferrer"&gt;Run database migrations as a Compose job before your app starts&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href="https://blog.hubfly.space/fix-failed-build?utm_source=devto&amp;amp;utm_medium=crosspost&amp;amp;utm_campaign=cron-job-in-docker-container" rel="noopener noreferrer"&gt;Build failed? How to read the build log and fix it fast&lt;/a&gt;&lt;/li&gt;
&lt;/ul&gt;

&lt;h2&gt;
  
  
  Go further on Hubfly space
&lt;/h2&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;Deploy the whole stack from Compose.&lt;/strong&gt; The &lt;a href="https://www.hubfly.space/docs/compose-json-reference/?ref=cron-job-in-docker-container" rel="noopener noreferrer"&gt;Compose reference&lt;/a&gt; shows how services, volumes and health checks map to containers.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Rebuild web and cron together on every push.&lt;/strong&gt; Hook your repo up with &lt;a href="https://www.hubfly.space/docs/deployment-pipelines/?ref=cron-job-in-docker-container" rel="noopener noreferrer"&gt;deployment pipelines&lt;/a&gt; so both containers always run the same commit.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Scale the web container, not the scheduler.&lt;/strong&gt; &lt;a href="https://www.hubfly.space/docs/scaling/?ref=cron-job-in-docker-container" rel="noopener noreferrer"&gt;Scaling&lt;/a&gt; covers auto-scale and replicas for the containers that serve traffic.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;&lt;a href="https://hubfly.space/?ref=cron-job-in-docker-container" rel="noopener noreferrer"&gt;&lt;strong&gt;Try it on Hubfly space&lt;/strong&gt;&lt;/a&gt;&lt;/p&gt;




&lt;p&gt;&lt;em&gt;By Octave · drafted with AI, reviewed by Octave · Last updated 5 November 2026&lt;/em&gt;&lt;/p&gt;

</description>
      <category>docker</category>
      <category>cron</category>
      <category>devops</category>
      <category>linux</category>
    </item>
    <item>
      <title>Docker Compose PostgreSQL environment variables, explained</title>
      <dc:creator>octave Nkurunziza</dc:creator>
      <pubDate>Tue, 10 Nov 2026 14:24:57 +0000</pubDate>
      <link>https://dev.to/octave_nkurunziza_afb0512/docker-compose-postgresql-environment-variables-explained-1e6g</link>
      <guid>https://dev.to/octave_nkurunziza_afb0512/docker-compose-postgresql-environment-variables-explained-1e6g</guid>
      <description>&lt;p&gt;&lt;em&gt;Last updated: 8 November 2026 · PostgreSQL 18 (official &lt;code&gt;postgres:18&lt;/code&gt; image, 18.6) · Docker Compose v2/v5&lt;/em&gt;&lt;/p&gt;

&lt;p&gt;Setting &lt;strong&gt;Docker Compose PostgreSQL environment variables&lt;/strong&gt; looks like three lines of YAML. Then you change the password, restart, and get &lt;code&gt;password authentication failed&lt;/code&gt;. Or your &lt;code&gt;.env&lt;/code&gt; file seems to be ignored. Or a &lt;code&gt;$&lt;/code&gt; in your password quietly disappears.&lt;/p&gt;

&lt;p&gt;This guide gives you a complete, copy-paste Compose setup for Postgres with a &lt;code&gt;.env&lt;/code&gt; file, a health check and an app that connects to it. It explains which variables the official image reads, when it reads them (only once, which is the cause of most "my password doesn't work" posts) and how to fix each common error. You'll know exactly where every value comes from, so the database starts the same way on your laptop and in production.&lt;/p&gt;

&lt;p&gt;&lt;a href="https://hubfly.space/?ref=docker-compose-postgresql-environment-variables" rel="noopener noreferrer"&gt;&lt;strong&gt;Try it on Hubfly space&lt;/strong&gt;&lt;/a&gt;: import the same Compose file and run Postgres next to your app.&lt;/p&gt;

&lt;h2&gt;
  
  
  The variables the postgres image reads
&lt;/h2&gt;

&lt;p&gt;The official image reads these at startup. &lt;strong&gt;Bold&lt;/strong&gt; ones are the ones you'll actually set.&lt;/p&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Variable&lt;/th&gt;
&lt;th&gt;Default&lt;/th&gt;
&lt;th&gt;What it does&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;&lt;strong&gt;&lt;code&gt;POSTGRES_PASSWORD&lt;/code&gt;&lt;/strong&gt;&lt;/td&gt;
&lt;td&gt;none (required)&lt;/td&gt;
&lt;td&gt;Password for the superuser. Startup fails without it unless auth is set to trust.&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;strong&gt;&lt;code&gt;POSTGRES_USER&lt;/code&gt;&lt;/strong&gt;&lt;/td&gt;
&lt;td&gt;&lt;code&gt;postgres&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Name of the superuser that's created.&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;strong&gt;&lt;code&gt;POSTGRES_DB&lt;/code&gt;&lt;/strong&gt;&lt;/td&gt;
&lt;td&gt;same as &lt;code&gt;POSTGRES_USER&lt;/code&gt;
&lt;/td&gt;
&lt;td&gt;Name of the first database.&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;POSTGRES_INITDB_ARGS&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;empty&lt;/td&gt;
&lt;td&gt;Extra flags for &lt;code&gt;initdb&lt;/code&gt;, like &lt;code&gt;--data-checksums&lt;/code&gt; or &lt;code&gt;--locale-provider=icu --icu-locale=en-US&lt;/code&gt;.&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;POSTGRES_INITDB_WALDIR&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;empty&lt;/td&gt;
&lt;td&gt;Puts the write-ahead log in a separate directory.&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;POSTGRES_HOST_AUTH_METHOD&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;the server's &lt;code&gt;password_encryption&lt;/code&gt; (&lt;code&gt;scram-sha-256&lt;/code&gt; on 14+)&lt;/td&gt;
&lt;td&gt;Auth method for network connections. Never set it to &lt;code&gt;trust&lt;/code&gt; on anything reachable.&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;PGDATA&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;
&lt;code&gt;/var/lib/postgresql/18/docker&lt;/code&gt; on 18&lt;/td&gt;
&lt;td&gt;Where the data files live. Leave it alone on 18.&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;
&lt;code&gt;*_FILE&lt;/code&gt; versions&lt;/td&gt;
&lt;td&gt;none&lt;/td&gt;
&lt;td&gt;
&lt;code&gt;POSTGRES_PASSWORD_FILE&lt;/code&gt;, &lt;code&gt;POSTGRES_USER_FILE&lt;/code&gt;, &lt;code&gt;POSTGRES_DB_FILE&lt;/code&gt; and &lt;code&gt;POSTGRES_INITDB_ARGS_FILE&lt;/code&gt; read the value from a file (for Docker secrets).&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;p&gt;Two things trip people up:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;There is no &lt;code&gt;POSTGRES_PORT&lt;/code&gt; or &lt;code&gt;POSTGRES_HOST&lt;/code&gt;.&lt;/strong&gt; Postgres listens on 5432 inside the container. Change the port on the host side of &lt;code&gt;ports:&lt;/code&gt; instead.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;All of these only matter the first time.&lt;/strong&gt; The image runs its setup only when the data directory is empty. More on that in Why your new password is ignored.&lt;/li&gt;
&lt;/ul&gt;

&lt;h2&gt;
  
  
  Step 1: Create the .env file
&lt;/h2&gt;

&lt;p&gt;Make a project folder, then generate a strong password that's safe to put in a URL:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;mkdir shop &lt;span class="o"&gt;&amp;amp;&amp;amp;&lt;/span&gt; &lt;span class="nb"&gt;cd&lt;/span&gt; shop
openssl rand -hex 24
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Hex output has only &lt;code&gt;0-9&lt;/code&gt; and &lt;code&gt;a-f&lt;/code&gt;, so you never have to escape or encode it. Create &lt;code&gt;.env&lt;/code&gt;:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;&lt;span class="c"&gt;# .env  (never commit this file)&lt;/span&gt;
&lt;span class="nv"&gt;POSTGRES_USER&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;shop
&lt;span class="nv"&gt;POSTGRES_PASSWORD&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;paste-the-48-character-hex-string-here
&lt;span class="nv"&gt;POSTGRES_DB&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;shop
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Keep it out of Git, and commit a template instead so teammates know what to fill in:&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;echo&lt;/span&gt; &lt;span class="s2"&gt;".env"&lt;/span&gt; &lt;span class="o"&gt;&amp;gt;&amp;gt;&lt;/span&gt; .gitignore
sed &lt;span class="s1"&gt;'s/^POSTGRES_PASSWORD=.*/POSTGRES_PASSWORD=change-me/'&lt;/span&gt; .env &lt;span class="o"&gt;&amp;gt;&lt;/span&gt; .env.example
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;&lt;strong&gt;Why:&lt;/strong&gt; the &lt;code&gt;.env&lt;/code&gt; file next to &lt;code&gt;compose.yaml&lt;/code&gt; is loaded automatically. You keep secrets out of the YAML, and each machine gets its own values.&lt;/p&gt;

&lt;h2&gt;
  
  
  Step 2: Write compose.yaml
&lt;/h2&gt;



&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight yaml"&gt;&lt;code&gt;&lt;span class="na"&gt;services&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
  &lt;span class="na"&gt;db&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
    &lt;span class="na"&gt;image&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s"&gt;postgres:18&lt;/span&gt;
    &lt;span class="na"&gt;restart&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s"&gt;unless-stopped&lt;/span&gt;
    &lt;span class="na"&gt;environment&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
      &lt;span class="na"&gt;POSTGRES_USER&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s"&gt;${POSTGRES_USER:-shop}&lt;/span&gt;
      &lt;span class="na"&gt;POSTGRES_PASSWORD&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s"&gt;${POSTGRES_PASSWORD:?Set POSTGRES_PASSWORD in .env}&lt;/span&gt;
      &lt;span class="na"&gt;POSTGRES_DB&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s"&gt;${POSTGRES_DB:-shop}&lt;/span&gt;
    &lt;span class="na"&gt;volumes&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
      &lt;span class="p"&gt;-&lt;/span&gt; &lt;span class="s"&gt;pgdata:/var/lib/postgresql&lt;/span&gt;
    &lt;span class="na"&gt;healthcheck&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
      &lt;span class="na"&gt;test&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="s2"&gt;"CMD-SHELL"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="s2"&gt;"pg_isready -h 127.0.0.1 -U $${POSTGRES_USER} -d $${POSTGRES_DB}"&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;
      &lt;span class="na"&gt;interval&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s"&gt;5s&lt;/span&gt;
      &lt;span class="na"&gt;timeout&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s"&gt;3s&lt;/span&gt;
      &lt;span class="na"&gt;retries&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="mi"&gt;10&lt;/span&gt;
      &lt;span class="na"&gt;start_period&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s"&gt;10s&lt;/span&gt;

  &lt;span class="na"&gt;api&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
    &lt;span class="na"&gt;build&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s"&gt;.&lt;/span&gt;
    &lt;span class="na"&gt;restart&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s"&gt;unless-stopped&lt;/span&gt;
    &lt;span class="na"&gt;environment&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
      &lt;span class="na"&gt;DATABASE_URL&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s"&gt;postgresql://${POSTGRES_USER:-shop}:${POSTGRES_PASSWORD}@db:5432/${POSTGRES_DB:-shop}&lt;/span&gt;
    &lt;span class="na"&gt;depends_on&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
      &lt;span class="na"&gt;db&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
        &lt;span class="na"&gt;condition&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s"&gt;service_healthy&lt;/span&gt;

&lt;span class="na"&gt;volumes&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
  &lt;span class="na"&gt;pgdata&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;What each part does:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;&lt;code&gt;${POSTGRES_PASSWORD:?...}&lt;/code&gt;&lt;/strong&gt; stops Compose before anything starts if the password is missing or empty. Without it you'd get a container that crashes on its first boot.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;&lt;code&gt;${POSTGRES_USER:-shop}&lt;/code&gt;&lt;/strong&gt; uses &lt;code&gt;shop&lt;/code&gt; when the variable isn't set.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;&lt;code&gt;pgdata:/var/lib/postgresql&lt;/code&gt;&lt;/strong&gt; is the right mount for Postgres 18. Older guides mount &lt;code&gt;/var/lib/postgresql/data&lt;/code&gt;; on 18 that makes the container refuse to start (see What can go wrong).&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;&lt;code&gt;$${POSTGRES_USER}&lt;/code&gt;&lt;/strong&gt; in the health check is escaped on purpose. &lt;code&gt;$$&lt;/code&gt; tells Compose "don't fill this in", so the shell inside the container reads the variable at run time. The full story is in &lt;a href="https://blog.hubfly.space/docker-health-checks-postgres-redis?utm_source=devto&amp;amp;utm_campaign=docker-compose-postgresql-environment-variables" rel="noopener noreferrer"&gt;Docker health checks that catch real problems&lt;/a&gt;.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;&lt;code&gt;-h 127.0.0.1&lt;/code&gt;&lt;/strong&gt; makes the check use TCP, so it can't pass against the temporary socket-only server the image runs during setup.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;&lt;code&gt;@db:5432&lt;/code&gt;&lt;/strong&gt;: inside Compose, the host is the service name, not &lt;code&gt;localhost&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;No &lt;code&gt;ports:&lt;/code&gt; on &lt;code&gt;db&lt;/code&gt;.&lt;/strong&gt; Your app reaches it over the private network. If you need to connect from your laptop, add &lt;code&gt;ports: ["127.0.0.1:5432:5432"]&lt;/code&gt; so it's only open on your own machine.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;Replace &lt;code&gt;build: .&lt;/code&gt; with your own app. Most Postgres drivers accept &lt;code&gt;DATABASE_URL&lt;/code&gt;, and libpq-based ones also read &lt;code&gt;PGHOST&lt;/code&gt;, &lt;code&gt;PGUSER&lt;/code&gt;, &lt;code&gt;PGPASSWORD&lt;/code&gt; and &lt;code&gt;PGDATABASE&lt;/code&gt;.&lt;/p&gt;

&lt;h2&gt;
  
  
  Step 3: Check the values before you start anything
&lt;/h2&gt;



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

&lt;/div&gt;



&lt;p&gt;This prints the file with every &lt;code&gt;${...}&lt;/code&gt; filled in, so you can see exactly what each container will get. If the password is missing you'll see:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;error while interpolating services.db.environment.POSTGRES_PASSWORD: required variable POSTGRES_PASSWORD is missing a value: Set POSTGRES_PASSWORD in .env
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;In the output, the health check still shows &lt;code&gt;$${POSTGRES_USER}&lt;/code&gt;. That's normal: &lt;code&gt;config&lt;/code&gt; prints a file you could run again, so it keeps the escape. The container receives a single &lt;code&gt;$&lt;/code&gt;.&lt;/p&gt;

&lt;p&gt;Then start it and connect:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;docker compose up -d
docker compose ps
docker compose &lt;span class="nb"&gt;exec&lt;/span&gt; db psql -U shop -d shop -c &lt;span class="s1"&gt;'select version();'&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;&lt;code&gt;exec&lt;/code&gt; needs no password: inside the container, local connections use trust auth. Network connections from other containers need the password.&lt;/p&gt;

&lt;h2&gt;
  
  
  .env vs env_file vs environment
&lt;/h2&gt;

&lt;p&gt;These three look alike and do different jobs. This is the single most confusing part of Compose.&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;
&lt;code&gt;.env&lt;/code&gt; (next to compose.yaml)&lt;/th&gt;
&lt;th&gt;&lt;code&gt;env_file:&lt;/code&gt;&lt;/th&gt;
&lt;th&gt;&lt;code&gt;environment:&lt;/code&gt;&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;Fills in &lt;code&gt;${VAR}&lt;/code&gt; in the YAML&lt;/td&gt;
&lt;td&gt;&lt;strong&gt;Yes&lt;/strong&gt;&lt;/td&gt;
&lt;td&gt;No&lt;/td&gt;
&lt;td&gt;No&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Puts variables inside the container&lt;/td&gt;
&lt;td&gt;No, only what you reference&lt;/td&gt;
&lt;td&gt;
&lt;strong&gt;Yes&lt;/strong&gt;, every line&lt;/td&gt;
&lt;td&gt;&lt;strong&gt;Yes&lt;/strong&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Wins when the same name is set twice&lt;/td&gt;
&lt;td&gt;n/a&lt;/td&gt;
&lt;td&gt;Loses to &lt;code&gt;environment:&lt;/code&gt;
&lt;/td&gt;
&lt;td&gt;&lt;strong&gt;Wins&lt;/strong&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;p&gt;So with this file:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight yaml"&gt;&lt;code&gt;&lt;span class="na"&gt;services&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
  &lt;span class="na"&gt;db&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
    &lt;span class="na"&gt;image&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s"&gt;postgres:18&lt;/span&gt;
    &lt;span class="na"&gt;env_file&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s"&gt;db.env&lt;/span&gt;          &lt;span class="c1"&gt;# contains POSTGRES_DB=ignored and ONLY_IN_DBENV=hello
&lt;/span&gt;    &lt;span class="na"&gt;environment&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
      &lt;span class="na"&gt;POSTGRES_DB&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s"&gt;orders&lt;/span&gt;
      &lt;span class="na"&gt;FROM_DBENV&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s"&gt;${ONLY_IN_DBENV:-not-visible}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;the container gets &lt;code&gt;POSTGRES_DB=orders&lt;/code&gt; (because &lt;code&gt;environment:&lt;/code&gt; wins) and &lt;code&gt;FROM_DBENV=not-visible&lt;/code&gt;, because &lt;code&gt;db.env&lt;/code&gt; is never used to fill in &lt;code&gt;${...}&lt;/code&gt;. If you want a file's values in the YAML, it has to be &lt;code&gt;.env&lt;/code&gt; or passed with &lt;code&gt;--env-file&lt;/code&gt;.&lt;/p&gt;

&lt;p&gt;Other rules worth knowing:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;Your shell wins over &lt;code&gt;.env&lt;/code&gt;.&lt;/strong&gt; &lt;code&gt;POSTGRES_PASSWORD=x docker compose up&lt;/code&gt; uses &lt;code&gt;x&lt;/code&gt;, whatever &lt;code&gt;.env&lt;/code&gt; says. An old &lt;code&gt;export&lt;/code&gt; in your terminal can silently override the file.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Compose looks for &lt;code&gt;.env&lt;/code&gt; next to &lt;code&gt;compose.yaml&lt;/code&gt;&lt;/strong&gt;, not in the folder you run the command from. Running from a subfolder still finds it.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Use a different file per environment&lt;/strong&gt; with &lt;code&gt;docker compose --env-file prod.env up -d&lt;/code&gt;.&lt;/li&gt;
&lt;/ul&gt;

&lt;h2&gt;
  
  
  Passwords with $, # or @ in them
&lt;/h2&gt;

&lt;p&gt;Generated hex passwords avoid all of this. If you must use a password with symbols, here's what happens.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;A &lt;code&gt;$&lt;/code&gt; gets eaten.&lt;/strong&gt; Compose fills in variables inside &lt;code&gt;.env&lt;/code&gt; and &lt;code&gt;env_file&lt;/code&gt; values too. This line:&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;POSTGRES_PASSWORD&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;Tr0ub&lt;span class="nv"&gt;$dor&lt;/span&gt;&lt;span class="o"&gt;&amp;amp;&lt;/span&gt;3
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;becomes &lt;code&gt;Tr0ub&amp;amp;3&lt;/code&gt;, because &lt;code&gt;$dor&lt;/code&gt; is read as an empty variable. Compose prints only a warning (&lt;code&gt;The "dor" variable is not set. Defaulting to a blank string.&lt;/code&gt;) and starts anyway. Your database is now created with a different password than the one in your password manager. Fix it with single quotes or &lt;code&gt;$$&lt;/code&gt;:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;&lt;span class="nv"&gt;POSTGRES_PASSWORD&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="s1"&gt;'Tr0ub$dor&amp;amp;3'&lt;/span&gt;
&lt;span class="c"&gt;# or&lt;/span&gt;
&lt;span class="nv"&gt;POSTGRES_PASSWORD&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;Tr0ub&lt;span class="nv"&gt;$dor&lt;/span&gt;&lt;span class="o"&gt;&amp;amp;&lt;/span&gt;3
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;&lt;strong&gt;A &lt;code&gt;#&lt;/code&gt; is fine&lt;/strong&gt; inside a value (&lt;code&gt;pass#word&lt;/code&gt;). Only &lt;code&gt;#&lt;/code&gt; with a space before it starts a comment.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;&lt;code&gt;@&lt;/code&gt;, &lt;code&gt;#&lt;/code&gt;, &lt;code&gt;/&lt;/code&gt;, &lt;code&gt;:&lt;/code&gt; and &lt;code&gt;%&lt;/code&gt; break &lt;code&gt;DATABASE_URL&lt;/code&gt;.&lt;/strong&gt; With the password &lt;code&gt;p@ss#w0rd/1&lt;/code&gt;, a client parses everything after the first &lt;code&gt;@&lt;/code&gt; as the host and fails with:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;could not translate host name "ss#w0rd" to address: Name or service not known
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Percent-encode the password in the URL only (the &lt;code&gt;POSTGRES_PASSWORD&lt;/code&gt; value stays as it is):&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;python3 -c &lt;span class="s2"&gt;"import urllib.parse,sys; print(urllib.parse.quote(sys.argv[1], safe=''))"&lt;/span&gt; &lt;span class="s1"&gt;'p@ss#w0rd/1'&lt;/span&gt;
&lt;span class="c"&gt;# p%40ss%23w0rd%2F1&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Then use &lt;code&gt;postgresql://shop:p%40ss%23w0rd%2F1@db:5432/shop&lt;/code&gt;.&lt;/p&gt;

&lt;h2&gt;
  
  
  Why your new password is ignored
&lt;/h2&gt;

&lt;p&gt;Here's why: &lt;strong&gt;setup only runs when the data directory is empty.&lt;/strong&gt; On the first start it creates the user, password and database from your variables. On every later start it finds existing data, prints this line and skips setup completely:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;PostgreSQL Database directory appears to contain a database; Skipping initialization
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;So changing &lt;code&gt;POSTGRES_PASSWORD&lt;/code&gt;, &lt;code&gt;POSTGRES_USER&lt;/code&gt; or &lt;code&gt;POSTGRES_DB&lt;/code&gt; in &lt;code&gt;.env&lt;/code&gt; does nothing to an existing volume. The old password still works and the new one fails with &lt;code&gt;FATAL: password authentication failed for user "shop"&lt;/code&gt;.&lt;/p&gt;

&lt;p&gt;You have two fixes.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Keep your data and change the password inside Postgres&lt;/strong&gt; (use this one in production):&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;docker compose &lt;span class="nb"&gt;exec&lt;/span&gt; db psql -U shop -d shop -c &lt;span class="s2"&gt;"ALTER USER shop WITH PASSWORD 'the-new-password';"&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Then put the same value in &lt;code&gt;.env&lt;/code&gt; and recreate the app so it picks it up: &lt;code&gt;docker compose up -d&lt;/code&gt;.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Start over with an empty database&lt;/strong&gt; (development only, this deletes all data):&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;docker compose down -v
docker compose up -d
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;&lt;code&gt;-v&lt;/code&gt; removes the named volume, so the next start runs setup again with your current &lt;code&gt;.env&lt;/code&gt;.&lt;/p&gt;

&lt;p&gt;The same rule applies to scripts in &lt;code&gt;/docker-entrypoint-initdb.d/&lt;/code&gt;. &lt;code&gt;.sh&lt;/code&gt;, &lt;code&gt;.sql&lt;/code&gt; and compressed &lt;code&gt;.sql&lt;/code&gt; (&lt;code&gt;.gz&lt;/code&gt;, &lt;code&gt;.xz&lt;/code&gt;, &lt;code&gt;.zst&lt;/code&gt;) files there run once, on the first start, sorted by name. They never run against an existing volume.&lt;/p&gt;

&lt;h2&gt;
  
  
  Use Docker secrets instead of a plain variable
&lt;/h2&gt;

&lt;p&gt;Anyone who can run &lt;code&gt;docker inspect&lt;/code&gt; on the container sees &lt;code&gt;POSTGRES_PASSWORD&lt;/code&gt; in plain text. A secret file is a step up, and the image supports it through &lt;code&gt;POSTGRES_PASSWORD_FILE&lt;/code&gt;:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight yaml"&gt;&lt;code&gt;&lt;span class="na"&gt;services&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
  &lt;span class="na"&gt;db&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
    &lt;span class="na"&gt;image&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s"&gt;postgres:18&lt;/span&gt;
    &lt;span class="na"&gt;restart&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s"&gt;unless-stopped&lt;/span&gt;
    &lt;span class="na"&gt;environment&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
      &lt;span class="na"&gt;POSTGRES_USER&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s"&gt;shop&lt;/span&gt;
      &lt;span class="na"&gt;POSTGRES_DB&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s"&gt;shop&lt;/span&gt;
      &lt;span class="na"&gt;POSTGRES_PASSWORD_FILE&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s"&gt;/run/secrets/db_password&lt;/span&gt;
    &lt;span class="na"&gt;secrets&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
      &lt;span class="p"&gt;-&lt;/span&gt; &lt;span class="s"&gt;db_password&lt;/span&gt;
    &lt;span class="na"&gt;volumes&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
      &lt;span class="p"&gt;-&lt;/span&gt; &lt;span class="s"&gt;pgdata:/var/lib/postgresql&lt;/span&gt;

&lt;span class="na"&gt;secrets&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
  &lt;span class="na"&gt;db_password&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
    &lt;span class="na"&gt;file&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s"&gt;./db_password.txt&lt;/span&gt;

&lt;span class="na"&gt;volumes&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
  &lt;span class="na"&gt;pgdata&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;





&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;openssl rand -hex 24 &lt;span class="o"&gt;&amp;gt;&lt;/span&gt; db_password.txt
chmod 600 db_password.txt
&lt;span class="nb"&gt;echo&lt;/span&gt; &lt;span class="s2"&gt;"db_password.txt"&lt;/span&gt; &lt;span class="o"&gt;&amp;gt;&amp;gt;&lt;/span&gt; .gitignore
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;A trailing newline in the file is fine; the image strips it. Don't set both &lt;code&gt;POSTGRES_PASSWORD&lt;/code&gt; and &lt;code&gt;POSTGRES_PASSWORD_FILE&lt;/code&gt;, or the container exits with &lt;code&gt;error: both POSTGRES_PASSWORD and POSTGRES_PASSWORD_FILE are set (but are exclusive)&lt;/code&gt;. Your app needs the password too, so either mount the same secret into it (if your framework reads &lt;code&gt;*_FILE&lt;/code&gt; variables) or keep it in &lt;code&gt;.env&lt;/code&gt; for the app only.&lt;/p&gt;

&lt;h2&gt;
  
  
  Running the same file on Hubfly space
&lt;/h2&gt;

&lt;p&gt;Hubfly space's Stack Composer imports Compose YAML: named volumes, health checks and &lt;code&gt;depends_on&lt;/code&gt; with &lt;code&gt;service_healthy&lt;/code&gt; carry over, and the &lt;code&gt;db&lt;/code&gt; → &lt;code&gt;api&lt;/code&gt; order becomes numbered deploy stages. &lt;code&gt;build:&lt;/code&gt; folders are built when you deploy the stack from your GitHub repo; otherwise point &lt;code&gt;api&lt;/code&gt; at a pushed image (&lt;code&gt;image: ghcr.io/your-org/shop-api:1.0&lt;/code&gt;). Three differences matter for environment variables:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;There's no &lt;code&gt;.env&lt;/code&gt; file on the server.&lt;/strong&gt; Set each variable as a row in the container's Environment Variables tab, and keep the &lt;strong&gt;Secret&lt;/strong&gt; toggle on for the password (it's on by default) so it's masked in logs. Variables set at the project level are shared by every container in the project and are stored encrypted (AES-256-GCM).&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Write a single &lt;code&gt;$&lt;/code&gt; in commands and health checks.&lt;/strong&gt; Stack Composer keeps &lt;code&gt;$$&lt;/code&gt; as two characters, so the shell turns it into a process ID. Use &lt;code&gt;$POSTGRES_USER&lt;/code&gt; there instead of &lt;code&gt;$${POSTGRES_USER}&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Bind mounts are skipped&lt;/strong&gt;, so files like &lt;code&gt;./init.sql:/docker-entrypoint-initdb.d/init.sql&lt;/code&gt; won't be there. Bake init scripts into your own image with a &lt;code&gt;COPY&lt;/code&gt; line instead.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;Imported services start on the shared tier (free within 360 hours a month) with auto-sleep. For a database, switch &lt;code&gt;db&lt;/code&gt; to Dedicated with 24/7 on: at 0.5 vCPU and 512 MB that's about $2.19 a month for compute (0.5 × $0.004 × 730 h + 0.5 GB × $0.002 × 730 h). Storage is billed per GB on top; Compose volumes are created as Balanced storage, about $0.017 per GB-month.&lt;/p&gt;

&lt;h2&gt;
  
  
  What can go wrong
&lt;/h2&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;What you see&lt;/th&gt;
&lt;th&gt;Why&lt;/th&gt;
&lt;th&gt;Fix&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;Error: Database is uninitialized and superuser password is not specified.&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;
&lt;code&gt;POSTGRES_PASSWORD&lt;/code&gt; is empty on the first start.&lt;/td&gt;
&lt;td&gt;Set it in &lt;code&gt;.env&lt;/code&gt;. Use &lt;code&gt;${POSTGRES_PASSWORD:?...}&lt;/code&gt; so Compose stops earlier with a clear message.&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;
&lt;code&gt;FATAL: password authentication failed for user "shop"&lt;/code&gt; after changing &lt;code&gt;.env&lt;/code&gt;
&lt;/td&gt;
&lt;td&gt;The volume already has data, so setup was skipped.&lt;/td&gt;
&lt;td&gt;
&lt;code&gt;ALTER USER&lt;/code&gt; (keeps data) or &lt;code&gt;docker compose down -v&lt;/code&gt; (deletes data).&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;FATAL: role "postgres" does not exist&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;You set &lt;code&gt;POSTGRES_USER=shop&lt;/code&gt;, so there's no &lt;code&gt;postgres&lt;/code&gt; user.&lt;/td&gt;
&lt;td&gt;Connect with &lt;code&gt;-U shop&lt;/code&gt;.&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;FATAL: database "shop" does not exist&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;The volume was created earlier with a different &lt;code&gt;POSTGRES_DB&lt;/code&gt;.&lt;/td&gt;
&lt;td&gt;Create it: &lt;code&gt;docker compose exec db createdb -U shop shop&lt;/code&gt;.&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;Error: in 18+, these Docker images are configured to store database data in a format which is compatible with "pg_ctlcluster"&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;You mounted &lt;code&gt;/var/lib/postgresql/data&lt;/code&gt; on Postgres 18, or reused a volume from 17 or older.&lt;/td&gt;
&lt;td&gt;Mount &lt;code&gt;/var/lib/postgresql&lt;/code&gt;. The image won't upgrade data from 17 or older for you: &lt;a href="https://blog.hubfly.space/upgrade-postgres-major-version-docker?utm_source=devto&amp;amp;utm_campaign=docker-compose-postgresql-environment-variables" rel="noopener noreferrer"&gt;upgrade it first with a dump and restore&lt;/a&gt; or &lt;code&gt;pg_upgrade&lt;/code&gt;.&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;The "xyz" variable is not set. Defaulting to a blank string.&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;A &lt;code&gt;$&lt;/code&gt; in a password or value.&lt;/td&gt;
&lt;td&gt;Single-quote the value or write &lt;code&gt;$$&lt;/code&gt;.&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;could not translate host name "..."&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;A special character in &lt;code&gt;DATABASE_URL&lt;/code&gt;, or &lt;code&gt;localhost&lt;/code&gt; used as the host.&lt;/td&gt;
&lt;td&gt;Percent-encode the password; use &lt;code&gt;db&lt;/code&gt; as the host.&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;
&lt;code&gt;connection refused&lt;/code&gt; from the app on first boot&lt;/td&gt;
&lt;td&gt;The app started before Postgres was ready.&lt;/td&gt;
&lt;td&gt;
&lt;code&gt;depends_on&lt;/code&gt; with &lt;code&gt;condition: service_healthy&lt;/code&gt;, as in Step 2.&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;A list entry like &lt;code&gt;- POSTGRES_DB:shop&lt;/code&gt; has no effect&lt;/td&gt;
&lt;td&gt;List form needs &lt;code&gt;=&lt;/code&gt;. Compose reads &lt;code&gt;POSTGRES_DB:shop&lt;/code&gt; as one variable name with no value.&lt;/td&gt;
&lt;td&gt;Write &lt;code&gt;- POSTGRES_DB=shop&lt;/code&gt;, or use the map form.&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;h2&gt;
  
  
  FAQ
&lt;/h2&gt;

&lt;h3&gt;
  
  
  How do I pass environment variables to Postgres in Docker Compose?
&lt;/h3&gt;

&lt;p&gt;Put them under &lt;code&gt;environment:&lt;/code&gt; on the &lt;code&gt;db&lt;/code&gt; service, and keep the values in a &lt;code&gt;.env&lt;/code&gt; file next to &lt;code&gt;compose.yaml&lt;/code&gt;, referenced as &lt;code&gt;${POSTGRES_PASSWORD}&lt;/code&gt;. Run &lt;code&gt;docker compose config&lt;/code&gt; to see the final values.&lt;/p&gt;

&lt;h3&gt;
  
  
  Why is my .env file not working in Docker Compose?
&lt;/h3&gt;

&lt;p&gt;Usually one of four things: the file isn't in the same folder as &lt;code&gt;compose.yaml&lt;/code&gt;, you used &lt;code&gt;env_file:&lt;/code&gt; and expected it to fill in &lt;code&gt;${...}&lt;/code&gt; (it doesn't), a variable exported in your shell is overriding it, or the volume already exists so Postgres ignores the new values.&lt;/p&gt;

&lt;h3&gt;
  
  
  What's the difference between .env and env_file in Docker Compose?
&lt;/h3&gt;

&lt;p&gt;&lt;code&gt;.env&lt;/code&gt; fills in &lt;code&gt;${VAR}&lt;/code&gt; placeholders in the YAML. &lt;code&gt;env_file:&lt;/code&gt; copies every line of a file into the container's environment. They can be the same file, but they're two separate features.&lt;/p&gt;

&lt;h3&gt;
  
  
  Do I need POSTGRES_USER and POSTGRES_DB?
&lt;/h3&gt;

&lt;p&gt;No. Only &lt;code&gt;POSTGRES_PASSWORD&lt;/code&gt; is required. Without the others you get a &lt;code&gt;postgres&lt;/code&gt; user and a &lt;code&gt;postgres&lt;/code&gt; database. Setting your own names is cleaner when several apps share a server.&lt;/p&gt;

&lt;h3&gt;
  
  
  How do I change the Postgres password in Docker?
&lt;/h3&gt;

&lt;p&gt;Run &lt;code&gt;ALTER USER name WITH PASSWORD '...'&lt;/code&gt; with &lt;code&gt;docker compose exec db psql&lt;/code&gt;, then update &lt;code&gt;.env&lt;/code&gt;. Changing only &lt;code&gt;.env&lt;/code&gt; does nothing once the volume has data.&lt;/p&gt;

&lt;h3&gt;
  
  
  Where does Postgres 18 store data in Docker?
&lt;/h3&gt;

&lt;p&gt;In &lt;code&gt;/var/lib/postgresql/18/docker&lt;/code&gt;. Mount the volume at &lt;code&gt;/var/lib/postgresql&lt;/code&gt; so a future upgrade can sit next to it. Coming from 17 or older? See &lt;a href="https://blog.hubfly.space/upgrade-postgres-major-version-docker?utm_source=devto&amp;amp;utm_campaign=docker-compose-postgresql-environment-variables" rel="noopener noreferrer"&gt;how to upgrade Postgres to a new major version in Docker&lt;/a&gt;.&lt;/p&gt;

&lt;h3&gt;
  
  
  Can I use Docker secrets with the postgres image?
&lt;/h3&gt;

&lt;p&gt;Yes. Set &lt;code&gt;POSTGRES_PASSWORD_FILE&lt;/code&gt; (or &lt;code&gt;POSTGRES_USER_FILE&lt;/code&gt;, &lt;code&gt;POSTGRES_DB_FILE&lt;/code&gt;) to the path of the secret, such as &lt;code&gt;/run/secrets/db_password&lt;/code&gt;.&lt;/p&gt;

&lt;h3&gt;
  
  
  Should I publish port 5432?
&lt;/h3&gt;

&lt;p&gt;Only if something outside Docker needs it, and then bind it to &lt;code&gt;127.0.0.1&lt;/code&gt;. Containers on the same Compose network reach Postgres without any &lt;code&gt;ports:&lt;/code&gt; entry.&lt;/p&gt;

&lt;h2&gt;
  
  
  Go further on Hubfly space
&lt;/h2&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;Skip running Postgres yourself.&lt;/strong&gt; A &lt;a href="https://www.hubfly.space/docs/databases/get-started/?ref=docker-compose-postgresql-environment-variables" rel="noopener noreferrer"&gt;managed PostgreSQL database&lt;/a&gt; gives you a ready connection string, and &lt;a href="https://www.hubfly.space/docs/databases/apps-and-bindings/?ref=docker-compose-postgresql-environment-variables" rel="noopener noreferrer"&gt;binding it to your app&lt;/a&gt; adds &lt;code&gt;DATABASE_URL&lt;/code&gt; to the app as a Secret.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Deploy the whole stack from Compose.&lt;/strong&gt; Follow the &lt;a href="https://www.hubfly.space/docs/compose/?ref=docker-compose-postgresql-environment-variables" rel="noopener noreferrer"&gt;Compose guide&lt;/a&gt; to import this file and run &lt;code&gt;db&lt;/code&gt; and &lt;code&gt;api&lt;/code&gt; in one project.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Reach a private database from your laptop&lt;/strong&gt; with a &lt;a href="https://www.hubfly.space/docs/cli/tunnels/?ref=docker-compose-postgresql-environment-variables" rel="noopener noreferrer"&gt;tunnel&lt;/a&gt; instead of publishing 5432.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;Related guides: &lt;a href="https://blog.hubfly.space/docker-health-checks-postgres-redis?utm_source=devto&amp;amp;utm_campaign=docker-compose-postgresql-environment-variables" rel="noopener noreferrer"&gt;Docker health checks that catch real problems&lt;/a&gt;, &lt;a href="https://blog.hubfly.space/docker-compose-migration-job-service-completed-successfully?utm_source=devto&amp;amp;utm_campaign=docker-compose-postgresql-environment-variables" rel="noopener noreferrer"&gt;Gate your app on a Postgres migration job&lt;/a&gt;, &lt;a href="https://blog.hubfly.space/docker-502-bad-gateway-bind-0-0-0-0?utm_source=devto&amp;amp;utm_campaign=docker-compose-postgresql-environment-variables" rel="noopener noreferrer"&gt;502 Bad Gateway in Docker? Bind to 0.0.0.0&lt;/a&gt;, &lt;a href="https://blog.hubfly.space/managed-postgresql-database-2-dollars-a-month?utm_source=devto&amp;amp;utm_campaign=docker-compose-postgresql-environment-variables" rel="noopener noreferrer"&gt;How to get a managed PostgreSQL database for about $2 a month&lt;/a&gt;.&lt;/p&gt;

&lt;p&gt;&lt;a href="https://hubfly.space/?ref=docker-compose-postgresql-environment-variables" rel="noopener noreferrer"&gt;&lt;strong&gt;Try it on Hubfly space&lt;/strong&gt;&lt;/a&gt;&lt;/p&gt;




&lt;p&gt;&lt;em&gt;By Octave · drafted with AI, reviewed by Octave · Last updated 8 November 2026&lt;/em&gt;&lt;/p&gt;

</description>
      <category>docker</category>
      <category>postgres</category>
      <category>devops</category>
      <category>tutorial</category>
    </item>
    <item>
      <title>Supabase vs Postgres: when you don't need the extras (2026)</title>
      <dc:creator>octave Nkurunziza</dc:creator>
      <pubDate>Tue, 10 Nov 2026 14:18:55 +0000</pubDate>
      <link>https://dev.to/octave_nkurunziza_afb0512/supabase-vs-postgres-when-you-dont-need-the-extras-2026-2612</link>
      <guid>https://dev.to/octave_nkurunziza_afb0512/supabase-vs-postgres-when-you-dont-need-the-extras-2026-2612</guid>
      <description>&lt;p&gt;&lt;em&gt;Last updated: 6 November 2026&lt;/em&gt;&lt;/p&gt;

&lt;p&gt;Supabase vs Postgres is a strange matchup, because Supabase &lt;em&gt;is&lt;/em&gt; Postgres. What you're really deciding is whether to pay for the pieces Supabase puts around it: sign-in, file storage, live updates, an auto-generated API and backups. For some apps that bundle is the best $25 you'll spend. For others it's $25 a month for a database plus features you never call. This guide shows what each piece costs on its own, where Supabase clearly wins, and how to keep your Supabase-style security rules working on plain Postgres if you move.&lt;/p&gt;

&lt;p&gt;&lt;a href="https://dashboard.hubfly.space/?ref=supabase-vs-postgres" rel="noopener noreferrer"&gt;&lt;strong&gt;Try it on Hubfly space&lt;/strong&gt;&lt;/a&gt;: a managed PostgreSQL 18 database starts at about $2 a month.&lt;/p&gt;

&lt;p&gt;Prices are as of 6 November 2026, in US dollars.&lt;/p&gt;

&lt;h2&gt;
  
  
  What Supabase adds on top of Postgres
&lt;/h2&gt;

&lt;p&gt;Every Supabase project is a regular Postgres database. Around it, Supabase runs several services and gives them one dashboard, one client library and one bill.&lt;/p&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Supabase piece&lt;/th&gt;
&lt;th&gt;What it does for you&lt;/th&gt;
&lt;th&gt;Plain-Postgres replacement&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;Auth&lt;/td&gt;
&lt;td&gt;Sign-up, login, OAuth, magic links; puts the user ID in every request&lt;/td&gt;
&lt;td&gt;An auth library in your API (e.g. &lt;a href="https://www.better-auth.com" rel="noopener noreferrer"&gt;Better Auth&lt;/a&gt; or &lt;a href="https://authjs.dev" rel="noopener noreferrer"&gt;Auth.js&lt;/a&gt;), or a hosted service like &lt;a href="https://clerk.com/pricing" rel="noopener noreferrer"&gt;Clerk&lt;/a&gt;
&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Auto-generated API&lt;/td&gt;
&lt;td&gt;Query tables straight from the browser, guarded by row-level security&lt;/td&gt;
&lt;td&gt;Your own small API (Express, FastAPI, Go…)&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Row-level security helpers&lt;/td&gt;
&lt;td&gt;
&lt;code&gt;auth.uid()&lt;/code&gt; inside policies&lt;/td&gt;
&lt;td&gt;The same policies, plus a 10-line shim (below)&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Storage&lt;/td&gt;
&lt;td&gt;Files in buckets with access rules&lt;/td&gt;
&lt;td&gt;Any S3-compatible bucket&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Realtime&lt;/td&gt;
&lt;td&gt;Live updates over WebSockets&lt;/td&gt;
&lt;td&gt;A Pusher-compatible server, or Postgres &lt;code&gt;LISTEN/NOTIFY&lt;/code&gt; in your API&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Edge Functions&lt;/td&gt;
&lt;td&gt;Server code next to the database&lt;/td&gt;
&lt;td&gt;Code in your API container&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Backups&lt;/td&gt;
&lt;td&gt;Daily backups on paid plans, optional point-in-time restore&lt;/td&gt;
&lt;td&gt;Managed backups from your provider, or scheduled &lt;code&gt;pg_dump&lt;/code&gt;
&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;p&gt;The pattern is clear: Supabase's extras replace code you would otherwise write and run. That's the trade. You pay less for plain Postgres, and you write (or wire up) more yourself.&lt;/p&gt;

&lt;h2&gt;
  
  
  Supabase pricing in 2026
&lt;/h2&gt;

&lt;p&gt;From &lt;a href="https://supabase.com/pricing" rel="noopener noreferrer"&gt;Supabase's pricing page&lt;/a&gt;:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;Free: $0.&lt;/strong&gt; 500 MB database, 50,000 monthly active users, 1 GB of files, 5 GB of egress, 2 active projects. No automatic backups. Projects are &lt;a href="https://supabase.com/docs/guides/platform/free-project-pausing" rel="noopener noreferrer"&gt;paused after 1 week of inactivity&lt;/a&gt;.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Pro: from $25/month.&lt;/strong&gt; Includes $10 of compute credit, which &lt;a href="https://supabase.com/docs/guides/platform/compute-and-disk" rel="noopener noreferrer"&gt;covers one Micro instance&lt;/a&gt; (shared CPU, 1 GB RAM). 8 GB of disk, 100,000 monthly active users, 100 GB of files, 250 GB of egress, daily backups kept 7 days.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Team: from $599/month.&lt;/strong&gt;&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;Pro overage rates: disk $0.125/GB, users $0.00325 each past 100,000, files $0.0213/GB, &lt;a href="https://supabase.com/docs/guides/platform/manage-your-usage/egress" rel="noopener noreferrer"&gt;egress $0.09/GB&lt;/a&gt; ($0.03 cached). Point-in-time restore is an add-on at $100/month for 7 days, and a custom domain is $10/month. Bigger compute costs extra: Small (2 GB) about $15, Medium (4 GB) about $60.&lt;/p&gt;

&lt;h2&gt;
  
  
  Plain Postgres pricing in 2026
&lt;/h2&gt;

&lt;p&gt;Here is what a database alone costs, roughly matched to Supabase Pro's 1 GB Micro instance.&lt;/p&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Provider&lt;/th&gt;
&lt;th&gt;Smallest sensible plan&lt;/th&gt;
&lt;th&gt;Monthly price&lt;/th&gt;
&lt;th&gt;Backups&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;&lt;a href="https://supabase.com/pricing" rel="noopener noreferrer"&gt;Supabase Pro&lt;/a&gt;&lt;/td&gt;
&lt;td&gt;Micro, 1 GB RAM, 8 GB disk&lt;/td&gt;
&lt;td&gt;$25 (includes auth, files, realtime)&lt;/td&gt;
&lt;td&gt;Daily, 7 days&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;a href="https://neon.com/pricing" rel="noopener noreferrer"&gt;Neon Launch&lt;/a&gt;&lt;/td&gt;
&lt;td&gt;Usage-based, billed per compute-hour&lt;/td&gt;
&lt;td&gt;Neon's own example: about $15 for 140 compute-hours and 1 GB&lt;/td&gt;
&lt;td&gt;Instant restore, $0.20/GB-month&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;a href="https://render.com/pricing" rel="noopener noreferrer"&gt;Render&lt;/a&gt;&lt;/td&gt;
&lt;td&gt;1 GB RAM&lt;/td&gt;
&lt;td&gt;$19 + storage at $0.30/GB&lt;/td&gt;
&lt;td&gt;Point-in-time restore, 3 days (Hobby) or 7 days (Pro)&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;a href="https://www.digitalocean.com/pricing/managed-databases" rel="noopener noreferrer"&gt;DigitalOcean&lt;/a&gt;&lt;/td&gt;
&lt;td&gt;1 vCPU, 1 GiB&lt;/td&gt;
&lt;td&gt;$15.15 with 10 GiB&lt;/td&gt;
&lt;td&gt;&lt;a href="https://docs.digitalocean.com/products/databases/postgresql/details/features/" rel="noopener noreferrer"&gt;Daily backups + 7-day point-in-time restore&lt;/a&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;a href="https://www.hubfly.space/docs/databases/pricing-and-limits/?ref=supabase-vs-postgres" rel="noopener noreferrer"&gt;Hubfly space&lt;/a&gt;&lt;/td&gt;
&lt;td&gt;Small, 0.5 vCPU, 1 GiB, 10 GiB&lt;/td&gt;
&lt;td&gt;$3.92&lt;/td&gt;
&lt;td&gt;No automatic backups yet (coming soon)&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;p&gt;Two things stand out. Supabase Pro is a fair price once you count everything in it. And if you only need the database, you can pay a fraction of that.&lt;/p&gt;

&lt;p&gt;Neon deserves a special mention: every plan now includes managed Better Auth, a Data API and Realtime at no separate charge, with auth for up to 60,000 monthly active users per project on Free and 1 million on paid plans. If what you want is "Postgres plus login", it's a strong middle ground.&lt;/p&gt;

&lt;h2&gt;
  
  
  Supabase vs Postgres: same app, two bills
&lt;/h2&gt;

&lt;p&gt;Take a typical small SaaS: a 2 GB database, 10,000 monthly active users, 20 GB of uploaded files and live updates in the UI.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;On Supabase Pro: $25.00 a month.&lt;/strong&gt; Everything fits inside Pro's included amounts: 2 GB of the 8 GB disk, 10,000 of 100,000 users, 20 GB of 100 GB of files. The free plan won't do, because the database alone is over its 500 MB limit.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;On plain Postgres plus your own pieces (Hubfly space): $9.09 a month.&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;Piece&lt;/th&gt;
&lt;th&gt;Size&lt;/th&gt;
&lt;th&gt;Monthly&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;Hubfly space managed PostgreSQL&lt;/td&gt;
&lt;td&gt;Small: 0.5 vCPU, 1 GiB, 10 GiB&lt;/td&gt;
&lt;td&gt;$3.92&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Hubfly space Cell container (runs your auth library and API)&lt;/td&gt;
&lt;td&gt;0.5 vCPU, 1 GB, 10 GB disk, always on&lt;/td&gt;
&lt;td&gt;$3.03&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Hubfly space Storage&lt;/td&gt;
&lt;td&gt;20 GB of files&lt;/td&gt;
&lt;td&gt;$0.22&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Managed Realtime&lt;/td&gt;
&lt;td&gt;Nano&lt;/td&gt;
&lt;td&gt;$1.92&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Auth&lt;/td&gt;
&lt;td&gt;Open-source library inside your API&lt;/td&gt;
&lt;td&gt;$0&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;strong&gt;Total&lt;/strong&gt;&lt;/td&gt;
&lt;td&gt;&lt;/td&gt;
&lt;td&gt;&lt;strong&gt;$9.09&lt;/strong&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;p&gt;How each number is worked out (730 hours a month; CPU $0.004 per vCPU-hour, memory $0.002 per GB-hour, storage $0.00001536 per GB-hour):&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;Database:&lt;/strong&gt; (0.5 × $0.004 + 1 × $0.002) = $0.004/h, plus the 30% management fee ($0.0012/h), plus 11 GiB of disk (10 GiB data + 1 GiB system) × $0.00001536 = $0.000169/h. Total $0.005369/h × 730 = &lt;strong&gt;$3.92&lt;/strong&gt;.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;API container:&lt;/strong&gt; (0.5 × $0.004 + 1 × $0.002) × 730 = $2.92, plus 10 GB × $0.00001536 × 730 = $0.11. Total &lt;strong&gt;$3.03&lt;/strong&gt;.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Files:&lt;/strong&gt; 20 GB × $0.00001536 × 730 = &lt;strong&gt;$0.22&lt;/strong&gt;.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Realtime:&lt;/strong&gt; the &lt;a href="https://www.hubfly.space/docs/realtime/pricing-and-limits/?ref=supabase-vs-postgres" rel="noopener noreferrer"&gt;Nano size is $1.92&lt;/a&gt;, with no per-message fee.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;Network transfer isn't in either total. Supabase Pro includes 250 GB of egress; check your provider's bandwidth terms before comparing heavy-download apps.&lt;/p&gt;

&lt;h3&gt;
  
  
  When the math flips
&lt;/h3&gt;

&lt;p&gt;The gap closes fast if you'd buy auth as a hosted service. Say the app grows to 150,000 monthly active users:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;Supabase Pro:&lt;/strong&gt; $25 + 50,000 extra users × $0.00325 = &lt;strong&gt;$187.50&lt;/strong&gt;.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Clerk Pro&lt;/strong&gt; (billed monthly) for sign-in alone, assuming all 150,000 count as Clerk's monthly retained users: $25 + 50,000 users × $0.02 + 50,000 users × $0.018 = &lt;strong&gt;$1,925&lt;/strong&gt;.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;An open-source auth library&lt;/strong&gt; in your own API: $0 extra, but you own password resets, OAuth setup and security updates.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;So Supabase's included users are a big deal if your alternative is a hosted auth service. They matter much less if you're happy running a library yourself.&lt;/p&gt;

&lt;h2&gt;
  
  
  When Supabase is the better choice
&lt;/h2&gt;

&lt;p&gt;Be honest about what you'd rebuild. Pick Supabase when:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;You'd otherwise buy hosted auth.&lt;/strong&gt; 100,000 monthly active users are included in Pro.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Your app is mostly frontend.&lt;/strong&gt; The auto-generated API plus row-level security means many apps need no backend server at all.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;You want backups handled.&lt;/strong&gt; Pro keeps 7 days of daily backups without you doing anything, and point-in-time restore is available as a $100/month add-on.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;You're prototyping.&lt;/strong&gt; The free plan gets you a database, login and file uploads in minutes. Just remember free projects pause after a week without activity.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;You value one dashboard.&lt;/strong&gt; One place for users, tables, files, logs and keys saves real time on a small team.&lt;/li&gt;
&lt;/ul&gt;

&lt;h2&gt;
  
  
  When plain Postgres is the better choice
&lt;/h2&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;You already have a backend.&lt;/strong&gt; If your API handles auth and business logic, Supabase's auto-generated API goes unused.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;You only need a database.&lt;/strong&gt; A 1 GB managed Postgres costs $3.92 to about $20 elsewhere versus $25.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;You want to own your auth data.&lt;/strong&gt; Users live in your own tables, with no provider-specific schema.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;The honest downside on Hubfly space today: managed Postgres runs on a single node, with no replicas, no high availability and no point-in-time restore, and automatic backups are still coming. Until they arrive, run your own &lt;code&gt;pg_dump&lt;/code&gt; on a schedule from any machine or job runner you already have, and keep the files somewhere else (the dump and restore commands are in &lt;a href="https://blog.hubfly.space/upgrade-postgres-major-version-docker?utm_source=devto&amp;amp;utm_campaign=supabase-vs-postgres" rel="noopener noreferrer"&gt;how to upgrade Postgres to a new major version in Docker&lt;/a&gt;). If you need automatic backups or failover today, Supabase Pro, DigitalOcean or Render are the safer picks.&lt;/p&gt;

&lt;h2&gt;
  
  
  Moving from Supabase to plain Postgres: the part guides skip
&lt;/h2&gt;

&lt;p&gt;Most migration guides say "run &lt;code&gt;pg_dump&lt;/code&gt;, then &lt;code&gt;pg_restore&lt;/code&gt;". On a typical Supabase schema, that fails, because your tables and policies point at things that only exist inside Supabase: the &lt;code&gt;auth&lt;/code&gt; schema, the &lt;code&gt;auth.uid()&lt;/code&gt; function and roles such as &lt;code&gt;authenticated&lt;/code&gt;.&lt;/p&gt;

&lt;p&gt;Here's a typical table from a Supabase app:&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;create&lt;/span&gt; &lt;span class="k"&gt;table&lt;/span&gt; &lt;span class="n"&gt;public&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;todos&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;
  &lt;span class="n"&gt;id&lt;/span&gt; &lt;span class="kt"&gt;bigint&lt;/span&gt; &lt;span class="n"&gt;generated&lt;/span&gt; &lt;span class="k"&gt;by&lt;/span&gt; &lt;span class="k"&gt;default&lt;/span&gt; &lt;span class="k"&gt;as&lt;/span&gt; &lt;span class="n"&gt;identity&lt;/span&gt; &lt;span class="k"&gt;primary&lt;/span&gt; &lt;span class="k"&gt;key&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="n"&gt;user_id&lt;/span&gt; &lt;span class="kt"&gt;uuid&lt;/span&gt; &lt;span class="k"&gt;not&lt;/span&gt; &lt;span class="kc"&gt;null&lt;/span&gt; &lt;span class="k"&gt;default&lt;/span&gt; &lt;span class="n"&gt;auth&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;uid&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="k"&gt;references&lt;/span&gt; &lt;span class="n"&gt;auth&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;users&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;id&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="k"&gt;on&lt;/span&gt; &lt;span class="k"&gt;delete&lt;/span&gt; &lt;span class="k"&gt;cascade&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="n"&gt;title&lt;/span&gt; &lt;span class="kt"&gt;text&lt;/span&gt; &lt;span class="k"&gt;not&lt;/span&gt; &lt;span class="kc"&gt;null&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="n"&gt;done&lt;/span&gt; &lt;span class="kt"&gt;boolean&lt;/span&gt; &lt;span class="k"&gt;not&lt;/span&gt; &lt;span class="kc"&gt;null&lt;/span&gt; &lt;span class="k"&gt;default&lt;/span&gt; &lt;span class="kc"&gt;false&lt;/span&gt;
&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="k"&gt;alter&lt;/span&gt; &lt;span class="k"&gt;table&lt;/span&gt; &lt;span class="n"&gt;public&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;todos&lt;/span&gt; &lt;span class="n"&gt;enable&lt;/span&gt; &lt;span class="k"&gt;row&lt;/span&gt; &lt;span class="n"&gt;level&lt;/span&gt; &lt;span class="n"&gt;security&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="k"&gt;create&lt;/span&gt; &lt;span class="n"&gt;policy&lt;/span&gt; &lt;span class="s2"&gt;"own todos read"&lt;/span&gt; &lt;span class="k"&gt;on&lt;/span&gt; &lt;span class="n"&gt;public&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;todos&lt;/span&gt;
  &lt;span class="k"&gt;for&lt;/span&gt; &lt;span class="k"&gt;select&lt;/span&gt; &lt;span class="k"&gt;to&lt;/span&gt; &lt;span class="n"&gt;authenticated&lt;/span&gt; &lt;span class="k"&gt;using&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="k"&gt;select&lt;/span&gt; &lt;span class="n"&gt;auth&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;uid&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="n"&gt;user_id&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="k"&gt;create&lt;/span&gt; &lt;span class="n"&gt;policy&lt;/span&gt; &lt;span class="s2"&gt;"own todos write"&lt;/span&gt; &lt;span class="k"&gt;on&lt;/span&gt; &lt;span class="n"&gt;public&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;todos&lt;/span&gt;
  &lt;span class="k"&gt;for&lt;/span&gt; &lt;span class="k"&gt;insert&lt;/span&gt; &lt;span class="k"&gt;to&lt;/span&gt; &lt;span class="n"&gt;authenticated&lt;/span&gt; &lt;span class="k"&gt;with&lt;/span&gt; &lt;span class="k"&gt;check&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="k"&gt;select&lt;/span&gt; &lt;span class="n"&gt;auth&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;uid&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="n"&gt;user_id&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Dump only your own schema and restore it into plain PostgreSQL, and you get this:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;pg_restore: error: could not execute query: ERROR:  schema "public" already exists
pg_restore: error: could not execute query: ERROR:  schema "auth" does not exist
LINE 3:     user_id uuid DEFAULT auth.uid() NOT NULL,
pg_restore: error: could not execute query: ERROR:  relation "public.todos" does not exist
...
pg_restore: warning: errors ignored on restore: 12
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The dangerous part: &lt;code&gt;pg_restore&lt;/code&gt; keeps going. It finishes with a warning and exit status 1, and your &lt;code&gt;todos&lt;/code&gt; table simply isn't there. Adding &lt;code&gt;--no-owner --no-acl&lt;/code&gt; doesn't help; the table still needs &lt;code&gt;auth.uid()&lt;/code&gt;.&lt;/p&gt;

&lt;p&gt;The fix is to recreate the small part of Supabase your schema depends on, before you restore.&lt;/p&gt;

&lt;h3&gt;
  
  
  Step 1: Dump your own tables
&lt;/h3&gt;

&lt;p&gt;Supabase &lt;a href="https://supabase.com/docs/guides/self-hosting/restore-from-platform" rel="noopener noreferrer"&gt;runs Postgres 17&lt;/a&gt;, and &lt;code&gt;pg_dump&lt;/code&gt; must be the same major version as the server or newer, so use version 17 or newer. The flags below are the same in every recent version. Copy a direct or session-mode connection string from your Supabase project's &lt;strong&gt;Connect&lt;/strong&gt; dialog.&lt;br&gt;
&lt;/p&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;"$SUPABASE_DB_URL"&lt;/span&gt; --format=custom --schema=public --file=public.dump
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;&lt;code&gt;--schema=public&lt;/code&gt; leaves out Supabase's own schemas (&lt;code&gt;auth&lt;/code&gt;, &lt;code&gt;storage&lt;/code&gt;, &lt;code&gt;realtime&lt;/code&gt; and others). Your users are in &lt;code&gt;auth.users&lt;/code&gt;, so export the columns you need separately:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;psql &lt;span class="s2"&gt;"$SUPABASE_DB_URL"&lt;/span&gt; -c &lt;span class="s2"&gt;"\copy (select id, email from auth.users) to 'users.csv' with csv header"&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;h3&gt;
  
  
  Step 2: Add the shim to the new database
&lt;/h3&gt;

&lt;p&gt;This recreates the three roles, a minimal &lt;code&gt;auth.users&lt;/code&gt; table and &lt;code&gt;auth.uid()&lt;/code&gt;. It reads the user ID the same way Supabase's own helpers do: first &lt;code&gt;request.jwt.claim.sub&lt;/code&gt;, then the &lt;code&gt;sub&lt;/code&gt; field of &lt;code&gt;request.jwt.claims&lt;/code&gt; (&lt;a href="https://supabase.com/kb/troubleshooting/permission-errors-when-granting-custom-roles-access-to-the-auth-schema" rel="noopener noreferrer"&gt;Supabase's example&lt;/a&gt;). Save it as &lt;code&gt;shim.sql&lt;/code&gt;:&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="c1"&gt;-- Make plain Postgres understand Supabase-style policies&lt;/span&gt;
&lt;span class="k"&gt;do&lt;/span&gt; $$ &lt;span class="k"&gt;begin&lt;/span&gt;
  &lt;span class="k"&gt;if&lt;/span&gt; &lt;span class="k"&gt;not&lt;/span&gt; &lt;span class="k"&gt;exists&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="k"&gt;select&lt;/span&gt; &lt;span class="k"&gt;from&lt;/span&gt; &lt;span class="n"&gt;pg_roles&lt;/span&gt; &lt;span class="k"&gt;where&lt;/span&gt; &lt;span class="n"&gt;rolname&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="s1"&gt;'anon'&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="k"&gt;then&lt;/span&gt; &lt;span class="k"&gt;create&lt;/span&gt; &lt;span class="n"&gt;role&lt;/span&gt; &lt;span class="n"&gt;anon&lt;/span&gt; &lt;span class="n"&gt;nologin&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt; &lt;span class="k"&gt;end&lt;/span&gt; &lt;span class="k"&gt;if&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="k"&gt;if&lt;/span&gt; &lt;span class="k"&gt;not&lt;/span&gt; &lt;span class="k"&gt;exists&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="k"&gt;select&lt;/span&gt; &lt;span class="k"&gt;from&lt;/span&gt; &lt;span class="n"&gt;pg_roles&lt;/span&gt; &lt;span class="k"&gt;where&lt;/span&gt; &lt;span class="n"&gt;rolname&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="s1"&gt;'authenticated'&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="k"&gt;then&lt;/span&gt; &lt;span class="k"&gt;create&lt;/span&gt; &lt;span class="n"&gt;role&lt;/span&gt; &lt;span class="n"&gt;authenticated&lt;/span&gt; &lt;span class="n"&gt;nologin&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt; &lt;span class="k"&gt;end&lt;/span&gt; &lt;span class="k"&gt;if&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="k"&gt;if&lt;/span&gt; &lt;span class="k"&gt;not&lt;/span&gt; &lt;span class="k"&gt;exists&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="k"&gt;select&lt;/span&gt; &lt;span class="k"&gt;from&lt;/span&gt; &lt;span class="n"&gt;pg_roles&lt;/span&gt; &lt;span class="k"&gt;where&lt;/span&gt; &lt;span class="n"&gt;rolname&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="s1"&gt;'service_role'&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="k"&gt;then&lt;/span&gt; &lt;span class="k"&gt;create&lt;/span&gt; &lt;span class="n"&gt;role&lt;/span&gt; &lt;span class="n"&gt;service_role&lt;/span&gt; &lt;span class="n"&gt;nologin&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt; &lt;span class="k"&gt;end&lt;/span&gt; &lt;span class="k"&gt;if&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="k"&gt;end&lt;/span&gt; $$&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="k"&gt;create&lt;/span&gt; &lt;span class="k"&gt;schema&lt;/span&gt; &lt;span class="k"&gt;if&lt;/span&gt; &lt;span class="k"&gt;not&lt;/span&gt; &lt;span class="k"&gt;exists&lt;/span&gt; &lt;span class="n"&gt;auth&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="k"&gt;create&lt;/span&gt; &lt;span class="k"&gt;table&lt;/span&gt; &lt;span class="k"&gt;if&lt;/span&gt; &lt;span class="k"&gt;not&lt;/span&gt; &lt;span class="k"&gt;exists&lt;/span&gt; &lt;span class="n"&gt;auth&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;users&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;id&lt;/span&gt; &lt;span class="kt"&gt;uuid&lt;/span&gt; &lt;span class="k"&gt;primary&lt;/span&gt; &lt;span class="k"&gt;key&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;email&lt;/span&gt; &lt;span class="kt"&gt;text&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="k"&gt;create&lt;/span&gt; &lt;span class="k"&gt;or&lt;/span&gt; &lt;span class="k"&gt;replace&lt;/span&gt; &lt;span class="k"&gt;function&lt;/span&gt; &lt;span class="nf"&gt;auth&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;uid&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="k"&gt;returns&lt;/span&gt; &lt;span class="kt"&gt;uuid&lt;/span&gt; &lt;span class="n"&gt;language&lt;/span&gt; &lt;span class="n"&gt;sql&lt;/span&gt; &lt;span class="n"&gt;stable&lt;/span&gt; &lt;span class="k"&gt;as&lt;/span&gt; $$
  &lt;span class="k"&gt;select&lt;/span&gt; &lt;span class="nb"&gt;coalesce&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;
    &lt;span class="nb"&gt;nullif&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nf"&gt;current_setting&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s1"&gt;'request.jwt.claim.sub'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="kc"&gt;true&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="s1"&gt;''&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nb"&gt;nullif&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nf"&gt;current_setting&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s1"&gt;'request.jwt.claims'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="kc"&gt;true&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="s1"&gt;''&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="o"&gt;::&lt;/span&gt;&lt;span class="kt"&gt;jsonb&lt;/span&gt; &lt;span class="o"&gt;-&amp;gt;&amp;gt;&lt;/span&gt; &lt;span class="s1"&gt;'sub'&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
  &lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="o"&gt;::&lt;/span&gt;&lt;span class="kt"&gt;uuid&lt;/span&gt;
$$&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="k"&gt;grant&lt;/span&gt; &lt;span class="n"&gt;usage&lt;/span&gt; &lt;span class="k"&gt;on&lt;/span&gt; &lt;span class="k"&gt;schema&lt;/span&gt; &lt;span class="n"&gt;auth&lt;/span&gt; &lt;span class="k"&gt;to&lt;/span&gt; &lt;span class="n"&gt;anon&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;authenticated&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;service_role&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="k"&gt;grant&lt;/span&gt; &lt;span class="n"&gt;execute&lt;/span&gt; &lt;span class="k"&gt;on&lt;/span&gt; &lt;span class="k"&gt;function&lt;/span&gt; &lt;span class="nf"&gt;auth&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;uid&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="k"&gt;to&lt;/span&gt; &lt;span class="n"&gt;anon&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;authenticated&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;service_role&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;It works with a regular admin user that can create roles; no superuser needed. That matters on managed databases, where you never get superuser. (It's also why &lt;code&gt;service_role&lt;/code&gt; here has no &lt;code&gt;BYPASSRLS&lt;/code&gt;: a role that doesn't have it can't give it, and admin users on managed databases normally don't have it.)&lt;/p&gt;

&lt;p&gt;The &lt;code&gt;nullif(…, '')&lt;/code&gt; is not decoration. Once a setting has been used on a connection, Postgres returns an empty string for it afterwards, not NULL. Without &lt;code&gt;nullif&lt;/code&gt;, the next request on that pooled connection fails with &lt;code&gt;invalid input syntax for type json&lt;/code&gt;.&lt;/p&gt;

&lt;h3&gt;
  
  
  Step 3: Load users, then restore
&lt;/h3&gt;



&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;psql &lt;span class="s2"&gt;"$NEW_DB_URL"&lt;/span&gt; -v &lt;span class="nv"&gt;ON_ERROR_STOP&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;1 -f shim.sql
psql &lt;span class="s2"&gt;"$NEW_DB_URL"&lt;/span&gt; -c &lt;span class="s2"&gt;"\copy auth.users (id, email) from 'users.csv' with csv header"&lt;/span&gt;

pg_restore --list public.dump &lt;span class="o"&gt;|&lt;/span&gt; grep -v -E &lt;span class="s1"&gt;'SCHEMA - public|COMMENT - SCHEMA public|DEFAULT ACL'&lt;/span&gt; &lt;span class="o"&gt;&amp;gt;&lt;/span&gt; restore.list
pg_restore --no-owner --exit-on-error --use-list=restore.list --dbname=&lt;span class="s2"&gt;"$NEW_DB_URL"&lt;/span&gt; public.dump
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The list file skips two kinds of entries. &lt;code&gt;CREATE SCHEMA public&lt;/code&gt; already exists and would otherwise be the first error. &lt;code&gt;DEFAULT ACL&lt;/code&gt; lines are Supabase's default grants for its own roles (for example &lt;code&gt;ALTER DEFAULT PRIVILEGES FOR ROLE postgres …&lt;/code&gt;); a non-superuser can't set them for another role, and the restore stops with &lt;code&gt;permission denied to change default privileges&lt;/code&gt;.&lt;/p&gt;

&lt;p&gt;Before restoring, list the grants the restore will run. Every role named there must exist in the new database:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;pg_restore --file=- --use-list=restore.list public.dump &lt;span class="o"&gt;|&lt;/span&gt; grep -E &lt;span class="s1"&gt;'^(GRANT|REVOKE)'&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;If the restore still stops with &lt;code&gt;role "…" does not exist&lt;/code&gt;, create that role with &lt;code&gt;create role &amp;lt;name&amp;gt; nologin;&lt;/code&gt; and run the restore again on a fresh database. Don't delete the table's ACL line instead: it holds all of that table's grants, including the one to &lt;code&gt;authenticated&lt;/code&gt; your policies need. For any other Supabase-only object the error names, remove its line from &lt;code&gt;restore.list&lt;/code&gt;. &lt;code&gt;--exit-on-error&lt;/code&gt; makes the restore stop at the first real problem instead of skipping tables. Keep the grants (no &lt;code&gt;--no-acl&lt;/code&gt;): your policies need the &lt;code&gt;authenticated&lt;/code&gt; role to have its table permissions.&lt;/p&gt;

&lt;p&gt;If a column default calls &lt;code&gt;extensions.uuid_generate_v4()&lt;/code&gt;, create that extension in a schema with the same name before restoring: &lt;code&gt;create schema extensions; create extension "uuid-ossp" schema extensions;&lt;/code&gt;.&lt;/p&gt;

&lt;h3&gt;
  
  
  Step 4: Run queries as the signed-in user
&lt;/h3&gt;

&lt;p&gt;Your policies now work, but only if each request tells Postgres who the user is. Create a login role for your app that does &lt;strong&gt;not&lt;/strong&gt; own the tables, and let it act as &lt;code&gt;authenticated&lt;/code&gt;:&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;create&lt;/span&gt; &lt;span class="n"&gt;role&lt;/span&gt; &lt;span class="n"&gt;shop_api&lt;/span&gt; &lt;span class="n"&gt;login&lt;/span&gt; &lt;span class="n"&gt;password&lt;/span&gt; &lt;span class="s1"&gt;'a-long-random-password'&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="k"&gt;grant&lt;/span&gt; &lt;span class="n"&gt;authenticated&lt;/span&gt; &lt;span class="k"&gt;to&lt;/span&gt; &lt;span class="n"&gt;shop_api&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Then wrap each request in a transaction that switches role and sets the user ID. Here it is for Node.js 22 with &lt;code&gt;pg&lt;/code&gt; 8:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight javascript"&gt;&lt;code&gt;&lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="nc"&gt;Pool&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nb"&gt;require&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s1"&gt;'pg'&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="n"&gt;pool&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;new&lt;/span&gt; &lt;span class="nc"&gt;Pool&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="n"&gt;connectionString&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nb"&gt;process&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;env&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="no"&gt;DATABASE_URL&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

&lt;span class="c1"&gt;// Run queries as one signed-in user, so Supabase-style RLS policies apply.&lt;/span&gt;
&lt;span class="k"&gt;async&lt;/span&gt; &lt;span class="kd"&gt;function&lt;/span&gt; &lt;span class="nf"&gt;asUser&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;userId&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;fn&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="n"&gt;client&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="n"&gt;pool&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;connect&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="k"&gt;try&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="n"&gt;client&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;query&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s1"&gt;'BEGIN'&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
    &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="n"&gt;client&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;query&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s1"&gt;'SET LOCAL ROLE authenticated'&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
    &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="n"&gt;client&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;query&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s2"&gt;"SELECT set_config('request.jwt.claims', $1, true)"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
      &lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="nb"&gt;JSON&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;stringify&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="n"&gt;sub&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="n"&gt;userId&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;role&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s1"&gt;'authenticated'&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
    &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="n"&gt;result&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="nf"&gt;fn&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;client&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
    &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="n"&gt;client&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;query&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s1"&gt;'COMMIT'&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
    &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="n"&gt;result&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="k"&gt;catch&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;err&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="n"&gt;client&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;query&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s1"&gt;'ROLLBACK'&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
    &lt;span class="k"&gt;throw&lt;/span&gt; &lt;span class="n"&gt;err&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="k"&gt;finally&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="n"&gt;client&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;release&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="p"&gt;}&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;

&lt;span class="c1"&gt;// Usage: const { rows } = await asUser(session.userId, c =&amp;gt; c.query('SELECT * FROM todos'));&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;&lt;code&gt;SET LOCAL&lt;/code&gt; and the &lt;code&gt;true&lt;/code&gt; in &lt;code&gt;set_config&lt;/code&gt; scope both to the transaction, so the next request on the same pooled connection starts clean. With this in place, user A sees only A's rows, and when user B tries to insert a row for user A, Postgres refuses with &lt;code&gt;new row violates row-level security policy for table "todos"&lt;/code&gt;.&lt;/p&gt;

&lt;h2&gt;
  
  
  What can go wrong
&lt;/h2&gt;

&lt;ol&gt;
&lt;li&gt;
&lt;strong&gt;Every user sees every row.&lt;/strong&gt; Your app connects as the table owner. Owners skip row-level security by default, so a policy that works on Supabase silently does nothing. Connect as a separate role like &lt;code&gt;shop_api&lt;/code&gt;, or run &lt;code&gt;alter table todos force row level security;&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Every query returns zero rows.&lt;/strong&gt; The role switch worked but the user ID didn't arrive, so &lt;code&gt;auth.uid()&lt;/code&gt; is NULL. Check that &lt;code&gt;set_config&lt;/code&gt; runs inside the same transaction as the query.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;&lt;code&gt;pg_restore&lt;/code&gt; "finished" but a table is missing.&lt;/strong&gt; You restored without &lt;code&gt;--exit-on-error&lt;/code&gt;. Look for &lt;code&gt;errors ignored on restore&lt;/code&gt; in the output, drop the new database (not your Supabase one) and restore again with the flag.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;&lt;code&gt;server version mismatch&lt;/code&gt; from &lt;code&gt;pg_dump&lt;/code&gt;.&lt;/strong&gt; Your local &lt;code&gt;pg_dump&lt;/code&gt; is older than the server. Install the PostgreSQL 17 or 18 client tools.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Uploaded files are gone.&lt;/strong&gt; &lt;a href="https://supabase.com/docs/guides/platform/backups" rel="noopener noreferrer"&gt;Supabase backups don't include Storage objects&lt;/a&gt;, and neither does &lt;code&gt;pg_dump&lt;/code&gt;: the database only holds their metadata. Copy the files with any S3 tool before you switch off the old project.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Everyone has to log in again.&lt;/strong&gt; Sessions and password hashes belong to Supabase Auth. Plan the move of logins separately; exporting &lt;code&gt;id&lt;/code&gt; and &lt;code&gt;email&lt;/code&gt; keeps your foreign keys intact, not your users' passwords.&lt;/li&gt;
&lt;/ol&gt;

&lt;h2&gt;
  
  
  FAQ
&lt;/h2&gt;

&lt;h3&gt;
  
  
  Is Supabase just Postgres?
&lt;/h3&gt;

&lt;p&gt;The database is regular Postgres, and you can connect to it with any Postgres client or ORM. Supabase adds auth, storage, realtime, an auto-generated API and backups around it, plus a few schemas and roles of its own.&lt;/p&gt;

&lt;h3&gt;
  
  
  Do I need Supabase or just Postgres?
&lt;/h3&gt;

&lt;p&gt;If you have your own backend and only need a database, plain Postgres is cheaper. If you'd otherwise buy hosted auth, or your app talks to the database straight from the browser, Supabase saves you real work.&lt;/p&gt;

&lt;h3&gt;
  
  
  How much does Supabase cost per month?
&lt;/h3&gt;

&lt;p&gt;Free is $0 with a 500 MB database and pausing after a week of inactivity. Pro starts at $25 a month with 8 GB of disk, 100,000 monthly active users and 250 GB of egress. Bigger compute, extra users and point-in-time restore cost extra.&lt;/p&gt;

&lt;h3&gt;
  
  
  Can I move my Supabase database to another Postgres host?
&lt;/h3&gt;

&lt;p&gt;Yes. Dump your own schema with &lt;code&gt;pg_dump&lt;/code&gt;, recreate &lt;code&gt;auth.uid()&lt;/code&gt; and the Supabase roles on the new database, then restore with &lt;code&gt;--exit-on-error&lt;/code&gt;. Files in Supabase Storage and user passwords need their own migration.&lt;/p&gt;

&lt;h3&gt;
  
  
  Will my RLS policies work outside Supabase?
&lt;/h3&gt;

&lt;p&gt;Yes, once &lt;code&gt;auth.uid()&lt;/code&gt; exists and each request sets the user ID in a transaction, as in Step 4. Policies are plain Postgres; only the helper function is Supabase-specific.&lt;/p&gt;

&lt;h3&gt;
  
  
  Do Supabase backups include my uploaded files?
&lt;/h3&gt;

&lt;p&gt;No. Supabase's backups cover the database only, which stores metadata about your files, not the files themselves.&lt;/p&gt;

&lt;h3&gt;
  
  
  What's the cheapest way to get Postgres plus login?
&lt;/h3&gt;

&lt;p&gt;Run an open-source auth library in your own API next to a small managed database, or use Neon, whose plans include managed Better Auth at no separate charge. For a broader price list, see &lt;a href="https://blog.hubfly.space/cheapest-database-small-app-2026?utm_source=devto&amp;amp;utm_campaign=supabase-vs-postgres" rel="noopener noreferrer"&gt;the cheapest database for a small app in 2026&lt;/a&gt;.&lt;/p&gt;

&lt;h2&gt;
  
  
  Go further on Hubfly space
&lt;/h2&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;Create the database&lt;/strong&gt; in a minute or two with &lt;a href="https://blog.hubfly.space/managed-postgresql-database-2-dollars-a-month?utm_source=devto&amp;amp;utm_campaign=supabase-vs-postgres" rel="noopener noreferrer"&gt;a managed PostgreSQL database for about $2 a month&lt;/a&gt;.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Find slow queries&lt;/strong&gt; after the move with Query insights: &lt;a href="https://blog.hubfly.space/find-fix-slow-postgresql-queries?utm_source=devto&amp;amp;utm_campaign=supabase-vs-postgres" rel="noopener noreferrer"&gt;how to find and fix slow PostgreSQL queries&lt;/a&gt;.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Store user uploads&lt;/strong&gt; in &lt;a href="https://www.hubfly.space/docs/storage/?ref=supabase-vs-postgres" rel="noopener noreferrer"&gt;Hubfly space Storage&lt;/a&gt;, an S3-compatible bucket at about $0.011 per GB a month.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;&lt;strong&gt;Keep your Postgres, drop the bill you don't use.&lt;/strong&gt; Create a managed PostgreSQL 18 database and pay for the size you pick. &lt;a href="https://dashboard.hubfly.space/?ref=supabase-vs-postgres" rel="noopener noreferrer"&gt;&lt;strong&gt;Try it on Hubfly space&lt;/strong&gt;&lt;/a&gt;&lt;/p&gt;




&lt;p&gt;&lt;em&gt;By Octave · drafted with AI, reviewed by Octave · Last updated 6 November 2026&lt;/em&gt;&lt;/p&gt;

</description>
      <category>supabase</category>
      <category>postgres</category>
      <category>database</category>
      <category>webdev</category>
    </item>
    <item>
      <title>How to Deploy FastAPI to Production (Step-by-Step Guide)</title>
      <dc:creator>octave Nkurunziza</dc:creator>
      <pubDate>Mon, 09 Nov 2026 08:22:48 +0000</pubDate>
      <link>https://dev.to/octave_nkurunziza_afb0512/how-to-deploy-fastapi-to-production-step-by-step-guide-2903</link>
      <guid>https://dev.to/octave_nkurunziza_afb0512/how-to-deploy-fastapi-to-production-step-by-step-guide-2903</guid>
      <description>&lt;p&gt;This guide shows you how to deploy FastAPI to production with Docker: a pinned Dockerfile, Postgres with Alembic migrations, HTTPS behind a proxy, health checks and a clean shutdown. It matters because &lt;code&gt;fastapi dev&lt;/code&gt; on your laptop hides the problems that break real deploys: redirects that switch to &lt;code&gt;http://&lt;/code&gt;, a container that takes 10 seconds to stop, migrations that run at the wrong moment, and API docs left open to the world. Every file below is complete. Copy them, change the names, and ship.&lt;/p&gt;

&lt;p&gt;&lt;a href="https://hubfly.space/?ref=how-to-deploy-fastapi-to-production" rel="noopener noreferrer"&gt;&lt;strong&gt;Try it on Hubfly space&lt;/strong&gt;&lt;/a&gt;: run the finished app with HTTPS for about $4.64 a month.&lt;/p&gt;

&lt;h2&gt;
  
  
  How to deploy FastAPI to production: what changes from dev
&lt;/h2&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;Development&lt;/th&gt;
&lt;th&gt;Production&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;Server&lt;/td&gt;
&lt;td&gt;
&lt;code&gt;fastapi dev&lt;/code&gt; (auto-reload)&lt;/td&gt;
&lt;td&gt;
&lt;code&gt;fastapi run&lt;/code&gt; (no reload, binds &lt;code&gt;0.0.0.0&lt;/code&gt;)&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Dependencies&lt;/td&gt;
&lt;td&gt;whatever &lt;code&gt;pip install&lt;/code&gt; gave you&lt;/td&gt;
&lt;td&gt;pinned versions in &lt;code&gt;requirements.txt&lt;/code&gt;
&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;User&lt;/td&gt;
&lt;td&gt;you&lt;/td&gt;
&lt;td&gt;a non-root user inside the container&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Database schema&lt;/td&gt;
&lt;td&gt;
&lt;code&gt;create_all()&lt;/code&gt; on startup&lt;/td&gt;
&lt;td&gt;Alembic migrations, run once per deploy&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;HTTPS&lt;/td&gt;
&lt;td&gt;none&lt;/td&gt;
&lt;td&gt;a proxy terminates TLS; the app trusts its headers&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;API docs&lt;/td&gt;
&lt;td&gt;open&lt;/td&gt;
&lt;td&gt;off, or behind a login&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Health&lt;/td&gt;
&lt;td&gt;"it loads"&lt;/td&gt;
&lt;td&gt;
&lt;code&gt;/healthz&lt;/code&gt; that checks the database&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;h2&gt;
  
  
  Step 1: Write the app
&lt;/h2&gt;

&lt;p&gt;The example is a small orders API called &lt;code&gt;shop-api&lt;/code&gt;. Layout:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;shop-api/
├── app/
│   ├── __init__.py      (empty)
│   ├── db.py
│   ├── models.py
│   └── main.py
├── migrations/          (created by Alembic in Step 3)
├── alembic.ini
├── requirements.txt
├── Dockerfile
├── .dockerignore
└── compose.yaml
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;&lt;code&gt;app/db.py&lt;/code&gt; reads the database URL from the environment, so the same image runs everywhere:&lt;br&gt;
&lt;/p&gt;

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

&lt;span class="kn"&gt;from&lt;/span&gt; &lt;span class="n"&gt;sqlalchemy&lt;/span&gt; &lt;span class="kn"&gt;import&lt;/span&gt; &lt;span class="n"&gt;create_engine&lt;/span&gt;
&lt;span class="kn"&gt;from&lt;/span&gt; &lt;span class="n"&gt;sqlalchemy.orm&lt;/span&gt; &lt;span class="kn"&gt;import&lt;/span&gt; &lt;span class="n"&gt;DeclarativeBase&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;sessionmaker&lt;/span&gt;

&lt;span class="n"&gt;engine&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nf"&gt;create_engine&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;
    &lt;span class="n"&gt;os&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;environ&lt;/span&gt;&lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="sh"&gt;"&lt;/span&gt;&lt;span class="s"&gt;DATABASE_URL&lt;/span&gt;&lt;span class="sh"&gt;"&lt;/span&gt;&lt;span class="p"&gt;],&lt;/span&gt;
    &lt;span class="n"&gt;pool_size&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="mi"&gt;5&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;          &lt;span class="c1"&gt;# per worker process
&lt;/span&gt;    &lt;span class="n"&gt;max_overflow&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="mi"&gt;5&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="n"&gt;pool_pre_ping&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="bp"&gt;True&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;   &lt;span class="c1"&gt;# drop dead connections after a DB restart
&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
&lt;span class="n"&gt;SessionLocal&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nf"&gt;sessionmaker&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;engine&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;


&lt;span class="k"&gt;class&lt;/span&gt; &lt;span class="nc"&gt;Base&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;DeclarativeBase&lt;/span&gt;&lt;span class="p"&gt;):&lt;/span&gt;
    &lt;span class="k"&gt;pass&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;&lt;code&gt;app/models.py&lt;/code&gt;:&lt;br&gt;
&lt;/p&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;sqlalchemy&lt;/span&gt; &lt;span class="kn"&gt;import&lt;/span&gt; &lt;span class="n"&gt;String&lt;/span&gt;
&lt;span class="kn"&gt;from&lt;/span&gt; &lt;span class="n"&gt;sqlalchemy.orm&lt;/span&gt; &lt;span class="kn"&gt;import&lt;/span&gt; &lt;span class="n"&gt;Mapped&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;mapped_column&lt;/span&gt;

&lt;span class="kn"&gt;from&lt;/span&gt; &lt;span class="n"&gt;app.db&lt;/span&gt; &lt;span class="kn"&gt;import&lt;/span&gt; &lt;span class="n"&gt;Base&lt;/span&gt;


&lt;span class="k"&gt;class&lt;/span&gt; &lt;span class="nc"&gt;Order&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;Base&lt;/span&gt;&lt;span class="p"&gt;):&lt;/span&gt;
    &lt;span class="n"&gt;__tablename__&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="sh"&gt;"&lt;/span&gt;&lt;span class="s"&gt;orders&lt;/span&gt;&lt;span class="sh"&gt;"&lt;/span&gt;

    &lt;span class="nb"&gt;id&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="n"&gt;Mapped&lt;/span&gt;&lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="nb"&gt;int&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nf"&gt;mapped_column&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;primary_key&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="bp"&gt;True&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
    &lt;span class="n"&gt;item&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="n"&gt;Mapped&lt;/span&gt;&lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="nb"&gt;str&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nf"&gt;mapped_column&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nc"&gt;String&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="mi"&gt;200&lt;/span&gt;&lt;span class="p"&gt;))&lt;/span&gt;
    &lt;span class="n"&gt;quantity&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="n"&gt;Mapped&lt;/span&gt;&lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="nb"&gt;int&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;&lt;code&gt;app/main.py&lt;/code&gt; adds three production details: docs that are off unless you ask for them, a health check that really touches the database, and a clean shutdown that closes the connection pool.&lt;br&gt;
&lt;/p&gt;

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

&lt;span class="kn"&gt;from&lt;/span&gt; &lt;span class="n"&gt;fastapi&lt;/span&gt; &lt;span class="kn"&gt;import&lt;/span&gt; &lt;span class="n"&gt;Depends&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;FastAPI&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;HTTPException&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;Request&lt;/span&gt;
&lt;span class="kn"&gt;from&lt;/span&gt; &lt;span class="n"&gt;pydantic&lt;/span&gt; &lt;span class="kn"&gt;import&lt;/span&gt; &lt;span class="n"&gt;BaseModel&lt;/span&gt;
&lt;span class="kn"&gt;from&lt;/span&gt; &lt;span class="n"&gt;sqlalchemy&lt;/span&gt; &lt;span class="kn"&gt;import&lt;/span&gt; &lt;span class="n"&gt;select&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;text&lt;/span&gt;
&lt;span class="kn"&gt;from&lt;/span&gt; &lt;span class="n"&gt;sqlalchemy.orm&lt;/span&gt; &lt;span class="kn"&gt;import&lt;/span&gt; &lt;span class="n"&gt;Session&lt;/span&gt;

&lt;span class="kn"&gt;from&lt;/span&gt; &lt;span class="n"&gt;app.db&lt;/span&gt; &lt;span class="kn"&gt;import&lt;/span&gt; &lt;span class="n"&gt;SessionLocal&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;engine&lt;/span&gt;
&lt;span class="kn"&gt;from&lt;/span&gt; &lt;span class="n"&gt;app.models&lt;/span&gt; &lt;span class="kn"&gt;import&lt;/span&gt; &lt;span class="n"&gt;Order&lt;/span&gt;

&lt;span class="n"&gt;SHOW_DOCS&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="n"&gt;os&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;getenv&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="sh"&gt;"&lt;/span&gt;&lt;span class="s"&gt;SHOW_DOCS&lt;/span&gt;&lt;span class="sh"&gt;"&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="o"&gt;==&lt;/span&gt; &lt;span class="sh"&gt;"&lt;/span&gt;&lt;span class="s"&gt;1&lt;/span&gt;&lt;span class="sh"&gt;"&lt;/span&gt;


&lt;span class="nd"&gt;@asynccontextmanager&lt;/span&gt;
&lt;span class="k"&gt;async&lt;/span&gt; &lt;span class="k"&gt;def&lt;/span&gt; &lt;span class="nf"&gt;lifespan&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;app&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="n"&gt;FastAPI&lt;/span&gt;&lt;span class="p"&gt;):&lt;/span&gt;
    &lt;span class="k"&gt;yield&lt;/span&gt;
    &lt;span class="n"&gt;engine&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;dispose&lt;/span&gt;&lt;span class="p"&gt;()&lt;/span&gt;  &lt;span class="c1"&gt;# close DB connections cleanly on shutdown
&lt;/span&gt;

&lt;span class="n"&gt;app&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nc"&gt;FastAPI&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;
    &lt;span class="n"&gt;title&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="sh"&gt;"&lt;/span&gt;&lt;span class="s"&gt;shop-api&lt;/span&gt;&lt;span class="sh"&gt;"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="n"&gt;lifespan&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="n"&gt;lifespan&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="c1"&gt;# openapi_url=None turns off /docs, /redoc AND /openapi.json
&lt;/span&gt;    &lt;span class="n"&gt;openapi_url&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="sh"&gt;"&lt;/span&gt;&lt;span class="s"&gt;/openapi.json&lt;/span&gt;&lt;span class="sh"&gt;"&lt;/span&gt; &lt;span class="k"&gt;if&lt;/span&gt; &lt;span class="n"&gt;SHOW_DOCS&lt;/span&gt; &lt;span class="k"&gt;else&lt;/span&gt; &lt;span class="bp"&gt;None&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
&lt;span class="p"&gt;)&lt;/span&gt;


&lt;span class="k"&gt;def&lt;/span&gt; &lt;span class="nf"&gt;get_db&lt;/span&gt;&lt;span class="p"&gt;():&lt;/span&gt;
    &lt;span class="k"&gt;with&lt;/span&gt; &lt;span class="nc"&gt;SessionLocal&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;session&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
        &lt;span class="k"&gt;yield&lt;/span&gt; &lt;span class="n"&gt;session&lt;/span&gt;


&lt;span class="k"&gt;class&lt;/span&gt; &lt;span class="nc"&gt;OrderIn&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;BaseModel&lt;/span&gt;&lt;span class="p"&gt;):&lt;/span&gt;
    &lt;span class="n"&gt;item&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nb"&gt;str&lt;/span&gt;
    &lt;span class="n"&gt;quantity&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nb"&gt;int&lt;/span&gt;


&lt;span class="nd"&gt;@app.get&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="sh"&gt;"&lt;/span&gt;&lt;span class="s"&gt;/healthz&lt;/span&gt;&lt;span class="sh"&gt;"&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
&lt;span class="k"&gt;def&lt;/span&gt; &lt;span class="nf"&gt;healthz&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;db&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="n"&gt;Session&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nc"&gt;Depends&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;get_db&lt;/span&gt;&lt;span class="p"&gt;)):&lt;/span&gt;
    &lt;span class="k"&gt;try&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
        &lt;span class="n"&gt;db&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;execute&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nf"&gt;text&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="sh"&gt;"&lt;/span&gt;&lt;span class="s"&gt;SELECT 1&lt;/span&gt;&lt;span class="sh"&gt;"&lt;/span&gt;&lt;span class="p"&gt;))&lt;/span&gt;
    &lt;span class="k"&gt;except&lt;/span&gt; &lt;span class="nb"&gt;Exception&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
        &lt;span class="k"&gt;raise&lt;/span&gt; &lt;span class="nc"&gt;HTTPException&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;status_code&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="mi"&gt;503&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;detail&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="sh"&gt;"&lt;/span&gt;&lt;span class="s"&gt;database unreachable&lt;/span&gt;&lt;span class="sh"&gt;"&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
    &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;&lt;span class="sh"&gt;"&lt;/span&gt;&lt;span class="s"&gt;status&lt;/span&gt;&lt;span class="sh"&gt;"&lt;/span&gt;&lt;span class="p"&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="nd"&gt;@app.post&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="sh"&gt;"&lt;/span&gt;&lt;span class="s"&gt;/orders&lt;/span&gt;&lt;span class="sh"&gt;"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;status_code&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="mi"&gt;201&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
&lt;span class="k"&gt;def&lt;/span&gt; &lt;span class="nf"&gt;create_order&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;order&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="n"&gt;OrderIn&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;db&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="n"&gt;Session&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nc"&gt;Depends&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;get_db&lt;/span&gt;&lt;span class="p"&gt;)):&lt;/span&gt;
    &lt;span class="n"&gt;row&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nc"&gt;Order&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;item&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="n"&gt;order&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;item&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;quantity&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="n"&gt;order&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;quantity&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
    &lt;span class="n"&gt;db&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;add&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;row&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
    &lt;span class="n"&gt;db&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;commit&lt;/span&gt;&lt;span class="p"&gt;()&lt;/span&gt;
    &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;&lt;span class="sh"&gt;"&lt;/span&gt;&lt;span class="s"&gt;id&lt;/span&gt;&lt;span class="sh"&gt;"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="n"&gt;row&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nb"&gt;id&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="sh"&gt;"&lt;/span&gt;&lt;span class="s"&gt;item&lt;/span&gt;&lt;span class="sh"&gt;"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="n"&gt;row&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;item&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="sh"&gt;"&lt;/span&gt;&lt;span class="s"&gt;quantity&lt;/span&gt;&lt;span class="sh"&gt;"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="n"&gt;row&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;quantity&lt;/span&gt;&lt;span class="p"&gt;}&lt;/span&gt;


&lt;span class="nd"&gt;@app.get&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="sh"&gt;"&lt;/span&gt;&lt;span class="s"&gt;/orders&lt;/span&gt;&lt;span class="sh"&gt;"&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
&lt;span class="k"&gt;def&lt;/span&gt; &lt;span class="nf"&gt;list_orders&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;db&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="n"&gt;Session&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nc"&gt;Depends&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;get_db&lt;/span&gt;&lt;span class="p"&gt;)):&lt;/span&gt;
    &lt;span class="n"&gt;rows&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="n"&gt;db&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;scalars&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nf"&gt;select&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;Order&lt;/span&gt;&lt;span class="p"&gt;).&lt;/span&gt;&lt;span class="nf"&gt;order_by&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;Order&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nb"&gt;id&lt;/span&gt;&lt;span class="p"&gt;)).&lt;/span&gt;&lt;span class="nf"&gt;all&lt;/span&gt;&lt;span class="p"&gt;()&lt;/span&gt;
    &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="p"&gt;[{&lt;/span&gt;&lt;span class="sh"&gt;"&lt;/span&gt;&lt;span class="s"&gt;id&lt;/span&gt;&lt;span class="sh"&gt;"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="n"&gt;r&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nb"&gt;id&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="sh"&gt;"&lt;/span&gt;&lt;span class="s"&gt;item&lt;/span&gt;&lt;span class="sh"&gt;"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="n"&gt;r&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;item&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="sh"&gt;"&lt;/span&gt;&lt;span class="s"&gt;quantity&lt;/span&gt;&lt;span class="sh"&gt;"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="n"&gt;r&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;quantity&lt;/span&gt;&lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="k"&gt;for&lt;/span&gt; &lt;span class="n"&gt;r&lt;/span&gt; &lt;span class="ow"&gt;in&lt;/span&gt; &lt;span class="n"&gt;rows&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;


&lt;span class="nd"&gt;@app.get&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="sh"&gt;"&lt;/span&gt;&lt;span class="s"&gt;/whoami&lt;/span&gt;&lt;span class="sh"&gt;"&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
&lt;span class="k"&gt;def&lt;/span&gt; &lt;span class="nf"&gt;whoami&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;request&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="n"&gt;Request&lt;/span&gt;&lt;span class="p"&gt;):&lt;/span&gt;
    &lt;span class="c1"&gt;# shows what the app believes about the caller (proxy headers check)
&lt;/span&gt;    &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;&lt;span class="sh"&gt;"&lt;/span&gt;&lt;span class="s"&gt;client&lt;/span&gt;&lt;span class="sh"&gt;"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="n"&gt;request&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;client&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;host&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="sh"&gt;"&lt;/span&gt;&lt;span class="s"&gt;scheme&lt;/span&gt;&lt;span class="sh"&gt;"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="n"&gt;request&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;url&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;scheme&lt;/span&gt;&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;&lt;strong&gt;Why &lt;code&gt;openapi_url=None&lt;/code&gt; and not &lt;code&gt;docs_url=None&lt;/code&gt;:&lt;/strong&gt; setting only &lt;code&gt;docs_url=None, redoc_url=None&lt;/code&gt; hides the pages but still serves your full schema at &lt;code&gt;/openapi.json&lt;/code&gt; (status 200). Turning off &lt;code&gt;openapi_url&lt;/code&gt; returns 404 on all three. Note that &lt;code&gt;fastapi run&lt;/code&gt; still prints "Documentation at &lt;a href="http://0.0.0.0:8000/docs" rel="noopener noreferrer"&gt;http://0.0.0.0:8000/docs&lt;/a&gt;" at startup; ignore that line. Set &lt;code&gt;SHOW_DOCS=1&lt;/code&gt; on staging when you want them.&lt;/p&gt;

&lt;p&gt;The endpoints use plain &lt;code&gt;def&lt;/code&gt;, not &lt;code&gt;async def&lt;/code&gt;, because SQLAlchemy's session here is synchronous. FastAPI runs &lt;code&gt;def&lt;/code&gt; endpoints in a thread pool, so they don't block the event loop.&lt;/p&gt;

&lt;h2&gt;
  
  
  Step 2: Pin your dependencies
&lt;/h2&gt;

&lt;p&gt;&lt;code&gt;requirements.txt&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;fastapi[standard]==0.162.2
sqlalchemy==2.1.8
psycopg[binary]==3.3.8
alembic==1.20.1
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;&lt;strong&gt;Why &lt;code&gt;fastapi[standard]&lt;/code&gt;:&lt;/strong&gt; plain &lt;code&gt;fastapi&lt;/code&gt; doesn't include the &lt;code&gt;fastapi&lt;/code&gt; command or Uvicorn. The &lt;code&gt;standard&lt;/code&gt; extra brings both, plus &lt;code&gt;uvloop&lt;/code&gt; and &lt;code&gt;httptools&lt;/code&gt; for speed. Pin exact versions so a rebuild next month gives you the same app.&lt;/p&gt;

&lt;h2&gt;
  
  
  Step 3: Add Alembic migrations
&lt;/h2&gt;

&lt;p&gt;Install the packages locally, then create the migrations folder:&lt;br&gt;
&lt;/p&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="nt"&gt;-r&lt;/span&gt; requirements.txt
alembic init migrations
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Open &lt;code&gt;migrations/env.py&lt;/code&gt; and make three changes. Add &lt;code&gt;import os&lt;/code&gt; at the top. Under &lt;code&gt;config = context.config&lt;/code&gt;, add:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight python"&gt;&lt;code&gt;&lt;span class="c1"&gt;# "%" must be doubled for configparser (URL-encoded passwords contain %)
&lt;/span&gt;&lt;span class="n"&gt;config&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;set_main_option&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="sh"&gt;"&lt;/span&gt;&lt;span class="s"&gt;sqlalchemy.url&lt;/span&gt;&lt;span class="sh"&gt;"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;os&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;environ&lt;/span&gt;&lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="sh"&gt;"&lt;/span&gt;&lt;span class="s"&gt;DATABASE_URL&lt;/span&gt;&lt;span class="sh"&gt;"&lt;/span&gt;&lt;span class="p"&gt;].&lt;/span&gt;&lt;span class="nf"&gt;replace&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="sh"&gt;"&lt;/span&gt;&lt;span class="s"&gt;%&lt;/span&gt;&lt;span class="sh"&gt;"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="sh"&gt;"&lt;/span&gt;&lt;span class="s"&gt;%%&lt;/span&gt;&lt;span class="sh"&gt;"&lt;/span&gt;&lt;span class="p"&gt;))&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;And replace &lt;code&gt;target_metadata = None&lt;/code&gt; with:&lt;br&gt;
&lt;/p&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;app.db&lt;/span&gt; &lt;span class="kn"&gt;import&lt;/span&gt; &lt;span class="n"&gt;Base&lt;/span&gt;  &lt;span class="c1"&gt;# noqa: E402
&lt;/span&gt;&lt;span class="kn"&gt;from&lt;/span&gt; &lt;span class="n"&gt;app&lt;/span&gt; &lt;span class="kn"&gt;import&lt;/span&gt; &lt;span class="n"&gt;models&lt;/span&gt;  &lt;span class="c1"&gt;# noqa: E402,F401
&lt;/span&gt;
&lt;span class="n"&gt;target_metadata&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="n"&gt;Base&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;metadata&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;&lt;strong&gt;The &lt;code&gt;%&lt;/code&gt; gotcha:&lt;/strong&gt; if your database password has special characters, you URL-encode them (&lt;code&gt;p@ss#word&lt;/code&gt; becomes &lt;code&gt;p%40ss%23word&lt;/code&gt;). Pass that URL straight to &lt;code&gt;set_main_option&lt;/code&gt; and Alembic crashes with &lt;code&gt;ValueError: invalid interpolation syntax ... at position 28&lt;/code&gt;, because &lt;code&gt;alembic.ini&lt;/code&gt; values go through Python's configparser. Doubling &lt;code&gt;%&lt;/code&gt; fixes it, and the app itself reads the URL unchanged.&lt;/p&gt;

&lt;p&gt;Also delete the example URL in &lt;code&gt;alembic.ini&lt;/code&gt; so nobody thinks it's used:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;sqlalchemy.url =
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Generate the first migration against a local database, then commit the file in &lt;code&gt;migrations/versions/&lt;/code&gt;:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;&lt;span class="nb"&gt;export &lt;/span&gt;&lt;span class="nv"&gt;DATABASE_URL&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="s2"&gt;"postgresql+psycopg://shop:your-password@localhost:5432/shop"&lt;/span&gt;
alembic revision &lt;span class="nt"&gt;--autogenerate&lt;/span&gt; &lt;span class="nt"&gt;-m&lt;/span&gt; &lt;span class="s2"&gt;"create orders"&lt;/span&gt;
alembic upgrade &lt;span class="nb"&gt;head&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;&lt;strong&gt;Why migrations run as their own step:&lt;/strong&gt; if you put &lt;code&gt;alembic upgrade head&lt;/code&gt; inside the app's startup, it runs once per worker and once per replica, and a failed migration still lets the app start against the old schema. A one-off job that must exit with code 0 before the API starts is easier to reason about. Step 5 wires that up.&lt;/p&gt;

&lt;h2&gt;
  
  
  Step 4: Write the Dockerfile
&lt;/h2&gt;



&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight docker"&gt;&lt;code&gt;&lt;span class="k"&gt;FROM&lt;/span&gt;&lt;span class="s"&gt; python:3.13-slim&lt;/span&gt;

&lt;span class="k"&gt;ENV&lt;/span&gt;&lt;span class="s"&gt; PYTHONDONTWRITEBYTECODE=1 \&lt;/span&gt;
    PYTHONUNBUFFERED=1 \
    PIP_NO_CACHE_DIR=1 \
    PIP_DISABLE_PIP_VERSION_CHECK=1

&lt;span class="k"&gt;WORKDIR&lt;/span&gt;&lt;span class="s"&gt; /code&lt;/span&gt;

&lt;span class="c"&gt;# Dependencies first, so code changes don't reinstall them&lt;/span&gt;
&lt;span class="k"&gt;COPY&lt;/span&gt;&lt;span class="s"&gt; requirements.txt .&lt;/span&gt;
&lt;span class="k"&gt;RUN &lt;/span&gt;pip &lt;span class="nb"&gt;install&lt;/span&gt; &lt;span class="nt"&gt;-r&lt;/span&gt; requirements.txt

&lt;span class="k"&gt;COPY&lt;/span&gt;&lt;span class="s"&gt; alembic.ini .&lt;/span&gt;
&lt;span class="k"&gt;COPY&lt;/span&gt;&lt;span class="s"&gt; migrations ./migrations&lt;/span&gt;
&lt;span class="k"&gt;COPY&lt;/span&gt;&lt;span class="s"&gt; app ./app&lt;/span&gt;

&lt;span class="c"&gt;# Never run the app as root&lt;/span&gt;
&lt;span class="k"&gt;RUN &lt;/span&gt;useradd &lt;span class="nt"&gt;--create-home&lt;/span&gt; &lt;span class="nt"&gt;--uid&lt;/span&gt; 10001 appuser
&lt;span class="k"&gt;USER&lt;/span&gt;&lt;span class="s"&gt; appuser&lt;/span&gt;

&lt;span class="k"&gt;EXPOSE&lt;/span&gt;&lt;span class="s"&gt; 8000&lt;/span&gt;

&lt;span class="k"&gt;HEALTHCHECK&lt;/span&gt;&lt;span class="s"&gt; --interval=30s --timeout=5s --start-period=20s --retries=3 \&lt;/span&gt;
  CMD ["python", "-c", "import urllib.request; urllib.request.urlopen('http://127.0.0.1:8000/healthz', timeout=4)"]

# Exec form: the app gets SIGTERM directly and shuts down cleanly
&lt;span class="k"&gt;CMD&lt;/span&gt;&lt;span class="s"&gt; ["fastapi", "run", "app/main.py", "--port", "8000"]&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;And &lt;code&gt;.dockerignore&lt;/code&gt;, so secrets and junk never reach the image:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;.git
.env
.venv
venv
__pycache__
*.pyc
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Three lines in that Dockerfile do most of the work:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;&lt;code&gt;USER appuser&lt;/code&gt;&lt;/strong&gt;: if someone finds a hole in your app, they land as an unprivileged user, not root.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;&lt;code&gt;HEALTHCHECK&lt;/code&gt;&lt;/strong&gt; uses Python's own &lt;code&gt;urllib&lt;/code&gt; because the slim image has no &lt;code&gt;curl&lt;/code&gt;. &lt;code&gt;urlopen&lt;/code&gt; raises on a 503, so the check fails when the database is down.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Exec-form &lt;code&gt;CMD&lt;/code&gt;&lt;/strong&gt; (the JSON array). This one is easy to get wrong. A common shortcut is &lt;code&gt;CMD alembic upgrade head &amp;amp;&amp;amp; fastapi run app/main.py&lt;/code&gt;. That shell form makes &lt;code&gt;sh&lt;/code&gt; process 1, and &lt;code&gt;sh&lt;/code&gt; doesn't pass &lt;code&gt;SIGTERM&lt;/code&gt; on to your app. &lt;strong&gt;&lt;code&gt;docker stop&lt;/code&gt; then waits its full 10 seconds and kills the container (exit code 137).&lt;/strong&gt; With the exec form, this app stops in &lt;strong&gt;under half a second with exit code 0&lt;/strong&gt;, after logging "Application shutdown complete". If you must chain commands in a shell, end with &lt;code&gt;exec fastapi run ...&lt;/code&gt;.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;Don't use the old &lt;code&gt;tiangolo/uvicorn-gunicorn-fastapi&lt;/code&gt; image. It's deprecated, and you don't need Gunicorn any more (see the FAQ).&lt;/p&gt;

&lt;h2&gt;
  
  
  Step 5: Run the whole stack with Compose
&lt;/h2&gt;

&lt;p&gt;&lt;code&gt;compose.yaml&lt;/code&gt;:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight yaml"&gt;&lt;code&gt;&lt;span class="na"&gt;services&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt;
  &lt;span class="na"&gt;db&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt;
    &lt;span class="na"&gt;image&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="s"&gt;postgres:18&lt;/span&gt;
    &lt;span class="na"&gt;environment&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt;
      &lt;span class="na"&gt;POSTGRES_USER&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="s"&gt;shop&lt;/span&gt;
      &lt;span class="na"&gt;POSTGRES_PASSWORD&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="s"&gt;${POSTGRES_PASSWORD:?set POSTGRES_PASSWORD in .env}&lt;/span&gt;
      &lt;span class="na"&gt;POSTGRES_DB&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="s"&gt;shop&lt;/span&gt;
    &lt;span class="na"&gt;volumes&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt;
      &lt;span class="pi"&gt;-&lt;/span&gt; &lt;span class="s"&gt;pgdata:/var/lib/postgresql&lt;/span&gt;
    &lt;span class="na"&gt;healthcheck&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt;
      &lt;span class="na"&gt;test&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="pi"&gt;[&lt;/span&gt;&lt;span class="s2"&gt;"&lt;/span&gt;&lt;span class="s"&gt;CMD-SHELL"&lt;/span&gt;&lt;span class="pi"&gt;,&lt;/span&gt; &lt;span class="s2"&gt;"&lt;/span&gt;&lt;span class="s"&gt;pg_isready&lt;/span&gt;&lt;span class="nv"&gt; &lt;/span&gt;&lt;span class="s"&gt;-U&lt;/span&gt;&lt;span class="nv"&gt; &lt;/span&gt;&lt;span class="s"&gt;shop&lt;/span&gt;&lt;span class="nv"&gt; &lt;/span&gt;&lt;span class="s"&gt;-d&lt;/span&gt;&lt;span class="nv"&gt; &lt;/span&gt;&lt;span class="s"&gt;shop"&lt;/span&gt;&lt;span class="pi"&gt;]&lt;/span&gt;
      &lt;span class="na"&gt;interval&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="s"&gt;5s&lt;/span&gt;
      &lt;span class="na"&gt;timeout&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="s"&gt;3s&lt;/span&gt;
      &lt;span class="na"&gt;retries&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="m"&gt;10&lt;/span&gt;
    &lt;span class="na"&gt;restart&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="s"&gt;unless-stopped&lt;/span&gt;

  &lt;span class="na"&gt;migrate&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt;
    &lt;span class="na"&gt;build&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="s"&gt;.&lt;/span&gt;
    &lt;span class="na"&gt;command&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="pi"&gt;[&lt;/span&gt;&lt;span class="s2"&gt;"&lt;/span&gt;&lt;span class="s"&gt;alembic"&lt;/span&gt;&lt;span class="pi"&gt;,&lt;/span&gt; &lt;span class="s2"&gt;"&lt;/span&gt;&lt;span class="s"&gt;upgrade"&lt;/span&gt;&lt;span class="pi"&gt;,&lt;/span&gt; &lt;span class="s2"&gt;"&lt;/span&gt;&lt;span class="s"&gt;head"&lt;/span&gt;&lt;span class="pi"&gt;]&lt;/span&gt;
    &lt;span class="na"&gt;environment&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt;
      &lt;span class="na"&gt;DATABASE_URL&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="s"&gt;postgresql+psycopg://shop:${POSTGRES_PASSWORD}@db:5432/shop&lt;/span&gt;
    &lt;span class="na"&gt;depends_on&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt;
      &lt;span class="na"&gt;db&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt;
        &lt;span class="na"&gt;condition&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="s"&gt;service_healthy&lt;/span&gt;
    &lt;span class="na"&gt;restart&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"&lt;/span&gt;&lt;span class="s"&gt;no"&lt;/span&gt;

  &lt;span class="na"&gt;api&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt;
    &lt;span class="na"&gt;build&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="s"&gt;.&lt;/span&gt;
    &lt;span class="na"&gt;environment&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt;
      &lt;span class="na"&gt;DATABASE_URL&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="s"&gt;postgresql+psycopg://shop:${POSTGRES_PASSWORD}@db:5432/shop&lt;/span&gt;
      &lt;span class="na"&gt;FORWARDED_ALLOW_IPS&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"&lt;/span&gt;&lt;span class="s"&gt;*"&lt;/span&gt;
    &lt;span class="na"&gt;ports&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt;
      &lt;span class="pi"&gt;-&lt;/span&gt; &lt;span class="s2"&gt;"&lt;/span&gt;&lt;span class="s"&gt;127.0.0.1:8000:8000"&lt;/span&gt;
    &lt;span class="na"&gt;depends_on&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt;
      &lt;span class="na"&gt;migrate&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt;
        &lt;span class="na"&gt;condition&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="s"&gt;service_completed_successfully&lt;/span&gt;
    &lt;span class="na"&gt;restart&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="s"&gt;unless-stopped&lt;/span&gt;
    &lt;span class="na"&gt;stop_grace_period&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="s"&gt;30s&lt;/span&gt;

&lt;span class="na"&gt;volumes&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt;
  &lt;span class="na"&gt;pgdata&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Create a &lt;code&gt;.env&lt;/code&gt; file next to it (and keep it out of Git):&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;POSTGRES_PASSWORD=change-me-long-random
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



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

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;docker compose up &lt;span class="nt"&gt;-d&lt;/span&gt; &lt;span class="nt"&gt;--build&lt;/span&gt;
curl http://127.0.0.1:8000/healthz
curl &lt;span class="nt"&gt;-X&lt;/span&gt; POST http://127.0.0.1:8000/orders &lt;span class="se"&gt;\&lt;/span&gt;
  &lt;span class="nt"&gt;-H&lt;/span&gt; &lt;span class="s2"&gt;"content-type: application/json"&lt;/span&gt; &lt;span class="se"&gt;\&lt;/span&gt;
  &lt;span class="nt"&gt;-d&lt;/span&gt; &lt;span class="s1"&gt;'{"item":"coffee beans","quantity":2}'&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Once the database is up, the first call returns &lt;code&gt;{"status":"ok"}&lt;/code&gt; and the second creates order 1: &lt;code&gt;{"id":1,"item":"coffee beans","quantity":2}&lt;/code&gt;.&lt;/p&gt;

&lt;p&gt;What each part buys you:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;&lt;code&gt;depends_on&lt;/code&gt; chain:&lt;/strong&gt; the database must be healthy, then &lt;code&gt;migrate&lt;/code&gt; must exit 0, then the API starts. A broken migration stops the deploy instead of serving errors.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;&lt;code&gt;/var/lib/postgresql&lt;/code&gt;&lt;/strong&gt;, not &lt;code&gt;/var/lib/postgresql/data&lt;/code&gt;: Postgres 18 images moved the data directory. The old path makes the container refuse to start. Use a password without &lt;code&gt;$&lt;/code&gt; in &lt;code&gt;.env&lt;/code&gt;: Compose treats &lt;code&gt;$word&lt;/code&gt; as a variable.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;&lt;code&gt;127.0.0.1:8000:8000&lt;/code&gt;:&lt;/strong&gt; the API port is open only to the machine itself. Only your proxy reaches it, which is what makes &lt;code&gt;FORWARDED_ALLOW_IPS: "*"&lt;/code&gt; safe (next step).&lt;/li&gt;
&lt;/ul&gt;

&lt;h2&gt;
  
  
  Step 6: Put HTTPS in front and trust the proxy
&lt;/h2&gt;

&lt;p&gt;FastAPI doesn't do TLS. A proxy in front does, then forwards the request with &lt;code&gt;X-Forwarded-Proto: https&lt;/code&gt; and &lt;code&gt;X-Forwarded-For: &amp;lt;client IP&amp;gt;&lt;/code&gt;. &lt;code&gt;fastapi run&lt;/code&gt; reads those headers, but by default it &lt;strong&gt;only trusts them from &lt;code&gt;127.0.0.1&lt;/code&gt;&lt;/strong&gt;.&lt;/p&gt;

&lt;p&gt;Here's what that means in practice. With the default setting and the proxy on another IP, a request for &lt;code&gt;/orders/&lt;/code&gt; with &lt;code&gt;X-Forwarded-Proto: https&lt;/code&gt; returns:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;HTTP/1.1 307 Temporary Redirect
location: http://api.example.com/orders
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Your HTTPS site just sent the browser to &lt;code&gt;http://&lt;/code&gt;. Every &lt;code&gt;request.url_for()&lt;/code&gt; link is wrong in the same way, and your logs show the proxy's IP instead of the visitor's. Set &lt;code&gt;FORWARDED_ALLOW_IPS="*"&lt;/code&gt; (or &lt;code&gt;--forwarded-allow-ips="*"&lt;/code&gt; on the command) and the same request returns &lt;code&gt;location: https://api.example.com/orders&lt;/code&gt;, with the real client IP.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Only trust &lt;code&gt;*&lt;/code&gt; when the proxy is the only thing that can reach the app.&lt;/strong&gt; On a managed platform, other containers in your project may still reach the app, so check what can. On a VPS, the &lt;code&gt;127.0.0.1:8000&lt;/code&gt; port binding above makes it true. If you'd rather name the proxy, list its IP: &lt;code&gt;FORWARDED_ALLOW_IPS="10.0.0.5"&lt;/code&gt;. Inside a container, Nginx's requests don't come from &lt;code&gt;127.0.0.1&lt;/code&gt;, so the default list ignores them.&lt;/p&gt;

&lt;h3&gt;
  
  
  On your own VPS: Nginx
&lt;/h3&gt;

&lt;p&gt;If you run the stack on a VPS, put Nginx on the host. This server block redirects HTTP, sets HSTS on the HTTPS side (browsers ignore it over plain HTTP), forwards the right headers and keeps WebSocket upgrades working:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight nginx"&gt;&lt;code&gt;&lt;span class="k"&gt;map&lt;/span&gt; &lt;span class="nv"&gt;$http_upgrade&lt;/span&gt; &lt;span class="nv"&gt;$connection_upgrade&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="kn"&gt;default&lt;/span&gt; &lt;span class="s"&gt;upgrade&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
    &lt;span class="kn"&gt;''&lt;/span&gt;      &lt;span class="s"&gt;''&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;

&lt;span class="k"&gt;upstream&lt;/span&gt; &lt;span class="s"&gt;shop_api&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="kn"&gt;server&lt;/span&gt; &lt;span class="nf"&gt;127.0.0.1&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="mi"&gt;8000&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
    &lt;span class="kn"&gt;keepalive&lt;/span&gt; &lt;span class="mi"&gt;16&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;

&lt;span class="k"&gt;server&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="kn"&gt;listen&lt;/span&gt; &lt;span class="mi"&gt;80&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
    &lt;span class="kn"&gt;server_name&lt;/span&gt; &lt;span class="s"&gt;api.example.com&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
    &lt;span class="kn"&gt;return&lt;/span&gt; &lt;span class="mi"&gt;301&lt;/span&gt; &lt;span class="s"&gt;https://&lt;/span&gt;&lt;span class="nv"&gt;$host$request_uri&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;

&lt;span class="k"&gt;server&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="kn"&gt;listen&lt;/span&gt; &lt;span class="mi"&gt;443&lt;/span&gt; &lt;span class="s"&gt;ssl&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
    &lt;span class="kn"&gt;server_name&lt;/span&gt; &lt;span class="s"&gt;api.example.com&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

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

    &lt;span class="kn"&gt;add_header&lt;/span&gt; &lt;span class="s"&gt;Strict-Transport-Security&lt;/span&gt; &lt;span class="s"&gt;"max-age=31536000"&lt;/span&gt; &lt;span class="s"&gt;always&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
    &lt;span class="kn"&gt;client_max_body_size&lt;/span&gt; &lt;span class="mi"&gt;10m&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

    &lt;span class="kn"&gt;location&lt;/span&gt; &lt;span class="n"&gt;/&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
        &lt;span class="kn"&gt;proxy_pass&lt;/span&gt; &lt;span class="s"&gt;http://shop_api&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
        &lt;span class="kn"&gt;proxy_http_version&lt;/span&gt; &lt;span class="mf"&gt;1.1&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
        &lt;span class="kn"&gt;proxy_set_header&lt;/span&gt; &lt;span class="s"&gt;Host&lt;/span&gt;              &lt;span class="nv"&gt;$host&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
        &lt;span class="kn"&gt;proxy_set_header&lt;/span&gt; &lt;span class="s"&gt;X-Forwarded-For&lt;/span&gt;   &lt;span class="nv"&gt;$proxy_add_x_forwarded_for&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
        &lt;span class="kn"&gt;proxy_set_header&lt;/span&gt; &lt;span class="s"&gt;X-Forwarded-Proto&lt;/span&gt; &lt;span class="nv"&gt;$scheme&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
        &lt;span class="kn"&gt;proxy_set_header&lt;/span&gt; &lt;span class="s"&gt;Upgrade&lt;/span&gt;           &lt;span class="nv"&gt;$http_upgrade&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
        &lt;span class="kn"&gt;proxy_set_header&lt;/span&gt; &lt;span class="s"&gt;Connection&lt;/span&gt;        &lt;span class="nv"&gt;$connection_upgrade&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
        &lt;span class="kn"&gt;proxy_read_timeout&lt;/span&gt; &lt;span class="s"&gt;60s&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
    &lt;span class="p"&gt;}&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Get the certificate with &lt;a href="https://certbot.eff.org/" rel="noopener noreferrer"&gt;Certbot&lt;/a&gt; for your OS, then run &lt;code&gt;sudo nginx -t&lt;/code&gt; before reloading. The &lt;code&gt;map&lt;/code&gt; block matters: many guides set &lt;code&gt;Connection "upgrade"&lt;/code&gt; on every request, which breaks keep-alive to the upstream. This version sends it only for real WebSocket requests.&lt;/p&gt;

&lt;h2&gt;
  
  
  How many workers?
&lt;/h2&gt;

&lt;p&gt;The FastAPI docs recommend &lt;strong&gt;one process per container&lt;/strong&gt; when something else (a platform, Kubernetes, Compose replicas) runs several containers for you. That's the setup above. Use &lt;code&gt;--workers N&lt;/code&gt; only when one container is all you have.&lt;/p&gt;

&lt;p&gt;Before you add workers, check the memory. Typical numbers for this app on Linux:&lt;/p&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Command&lt;/th&gt;
&lt;th&gt;Processes&lt;/th&gt;
&lt;th&gt;Memory (RSS)&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;fastapi run app/main.py&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;1&lt;/td&gt;
&lt;td&gt;about 102 MB&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;fastapi run app/main.py --workers 2&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;parent + helper + 2 workers&lt;/td&gt;
&lt;td&gt;about 320 MB (96 + 14 + 101 + 108)&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;p&gt;The parent process imports your app too, so going from 1 to 2 workers triples memory. On a 512 MB container, one process leaves plenty of headroom; two is the limit. Your app's imports decide the real numbers, so measure with &lt;code&gt;docker stats&lt;/code&gt;.&lt;/p&gt;

&lt;p&gt;CPU is the other half. A worker only helps when the container has a whole CPU to give it. On 0.5 vCPU, a second worker just competes for the same slice. Add replicas instead.&lt;/p&gt;

&lt;h2&gt;
  
  
  Deploy it on Hubfly space
&lt;/h2&gt;

&lt;p&gt;Hubfly space Cell runs containers straight from your Git repository, and a root &lt;code&gt;Dockerfile&lt;/code&gt; is used as-is. That's the file from Step 4, so nothing changes. The platform's edge handles HTTPS, so you skip Nginx and Certbot.&lt;/p&gt;

&lt;ol&gt;
&lt;li&gt;
&lt;strong&gt;Create a project&lt;/strong&gt;, pick a region, and set a monthly budget cap to stop spending past a set amount.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Add Postgres.&lt;/strong&gt; Click &lt;strong&gt;Create Container&lt;/strong&gt; → &lt;strong&gt;Docker image&lt;/strong&gt; → &lt;code&gt;postgres:18&lt;/code&gt;. Choose the &lt;strong&gt;Dedicated Tier&lt;/strong&gt; at 0.5 vCPU and 512 MB, and turn &lt;strong&gt;Auto Sleep&lt;/strong&gt; off. Under &lt;strong&gt;Environment Variables&lt;/strong&gt;, add &lt;code&gt;POSTGRES_USER=shop&lt;/code&gt;, &lt;code&gt;POSTGRES_DB=shop&lt;/code&gt; and &lt;code&gt;POSTGRES_PASSWORD&lt;/code&gt; (keep &lt;strong&gt;Secret&lt;/strong&gt; on). Under &lt;strong&gt;Storage&lt;/strong&gt;, add a 10 GB volume (keep the &lt;strong&gt;Balanced&lt;/strong&gt; performance mode) mounted at &lt;code&gt;/var/lib/postgresql&lt;/code&gt;. On &lt;strong&gt;Review&lt;/strong&gt;, copy the &lt;strong&gt;Private Network DNS&lt;/strong&gt; name.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Add the API.&lt;/strong&gt; Click &lt;strong&gt;Create Container&lt;/strong&gt; → &lt;strong&gt;Git repository&lt;/strong&gt; and pick your repo. Leave &lt;strong&gt;Automatically detect the build&lt;/strong&gt; on; the root Dockerfile wins. Choose Dedicated 0.5 vCPU / 512 MB with Auto Sleep off. Add &lt;code&gt;DATABASE_URL=postgresql+psycopg://shop:&amp;lt;password&amp;gt;@&amp;lt;private-dns-name&amp;gt;:5432/shop&lt;/code&gt; (Secret on).&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Run migrations on every start.&lt;/strong&gt; Do this in the wizard's &lt;strong&gt;Configuration&lt;/strong&gt; step, before the first deploy. In &lt;strong&gt;Process Settings&lt;/strong&gt; → &lt;strong&gt;Command&lt;/strong&gt;, enter one argument per line: &lt;code&gt;sh&lt;/code&gt;, then &lt;code&gt;-c&lt;/code&gt;, then &lt;code&gt;alembic upgrade head &amp;amp;&amp;amp; exec fastapi run app/main.py --port 8000&lt;/code&gt;. Set the working directory to &lt;code&gt;/code&lt;/code&gt; if it isn't already, because Alembic finds &lt;code&gt;alembic.ini&lt;/code&gt; from there. With a single container this is safe: the migration runs before the app starts, a failed migration stops the container instead of serving new code on the old schema, and &lt;code&gt;exec&lt;/code&gt; keeps the clean shutdown from Step 4. When you add replicas, move the migration into a separate job (a Compose stack on Hubfly space imports a &lt;code&gt;restart: "no"&lt;/code&gt; service as a Job).&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Add the health check.&lt;/strong&gt; In &lt;strong&gt;Configuration&lt;/strong&gt; → &lt;strong&gt;Health Check&lt;/strong&gt;, paste the same check in Docker's shell form: &lt;code&gt;CMD-SHELL python -c "import urllib.request; urllib.request.urlopen('http://127.0.0.1:8000/healthz', timeout=4)"&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Get a URL.&lt;/strong&gt; Open &lt;strong&gt;Network&lt;/strong&gt; → &lt;strong&gt;Add Domain&lt;/strong&gt; → &lt;strong&gt;Auto Endpoint&lt;/strong&gt;. The port scan suggests 8000. TLS and Force HTTPS are on by default. Attach your own domain from the same screen when you're ready.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Check the scheme.&lt;/strong&gt; Open &lt;code&gt;https://&amp;lt;your-endpoint&amp;gt;/orders/&lt;/code&gt;. If the redirect points to &lt;code&gt;http://&lt;/code&gt;, add &lt;code&gt;FORWARDED_ALLOW_IPS=*&lt;/code&gt; to the API container and restart it. Every container in your project can reach this one on the private network, so keep workloads you don't trust in a separate project.&lt;/li&gt;
&lt;/ol&gt;

&lt;p&gt;&lt;strong&gt;What it costs&lt;/strong&gt;, at Hubfly space's rates ($0.004 per vCPU-hour, $0.002 per GB-hour of RAM, 730 hours a month):&lt;/p&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Item&lt;/th&gt;
&lt;th&gt;Math&lt;/th&gt;
&lt;th&gt;Per month&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;API, 0.5 vCPU / 512 MB, always on&lt;/td&gt;
&lt;td&gt;0.5 × 0.004 × 730 + 0.5 × 0.002 × 730 + 4 GB disk&lt;/td&gt;
&lt;td&gt;$2.23&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Postgres, same size&lt;/td&gt;
&lt;td&gt;same&lt;/td&gt;
&lt;td&gt;$2.23&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;10 GB Balanced volume&lt;/td&gt;
&lt;td&gt;10 × 0.00001536 × 1.5 × 730&lt;/td&gt;
&lt;td&gt;$0.17&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;strong&gt;Total&lt;/strong&gt;&lt;/td&gt;
&lt;td&gt;&lt;/td&gt;
&lt;td&gt;&lt;strong&gt;about $4.64&lt;/strong&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;p&gt;There's no fee per project, seat or custom domain. Want to try it first? The shared tier is free for 360 hours a month for both containers together (0.3 vCPU / 256 MB, sleeps when idle), and the single-process app fits in its 256 MB.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Where something else wins:&lt;/strong&gt; if you already run Kubernetes, keep FastAPI there with one process per pod. If your API gets a few requests a day, a serverless function costs less than any always-on container.&lt;/p&gt;

&lt;h2&gt;
  
  
  What can go wrong
&lt;/h2&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Symptom&lt;/th&gt;
&lt;th&gt;Cause&lt;/th&gt;
&lt;th&gt;Fix&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;Redirects or &lt;code&gt;url_for&lt;/code&gt; links use &lt;code&gt;http://&lt;/code&gt; on an HTTPS site&lt;/td&gt;
&lt;td&gt;Proxy headers not trusted&lt;/td&gt;
&lt;td&gt;Set &lt;code&gt;FORWARDED_ALLOW_IPS&lt;/code&gt; to the proxy IP, or &lt;code&gt;*&lt;/code&gt; when only the proxy can reach the app&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Logs show the proxy's IP for every visitor&lt;/td&gt;
&lt;td&gt;Same as above&lt;/td&gt;
&lt;td&gt;Same fix&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;502 Bad Gateway from the proxy&lt;/td&gt;
&lt;td&gt;App listening on &lt;code&gt;127.0.0.1&lt;/code&gt; inside the container&lt;/td&gt;
&lt;td&gt;
&lt;code&gt;fastapi run&lt;/code&gt; binds &lt;code&gt;0.0.0.0&lt;/code&gt; by default; don't pass &lt;code&gt;--host 127.0.0.1&lt;/code&gt; in a container (&lt;a href="https://blog.hubfly.space/docker-502-bad-gateway-bind-0-0-0-0?utm_source=devto&amp;amp;utm_campaign=how-to-deploy-fastapi-to-production" rel="noopener noreferrer"&gt;the 502 fix&lt;/a&gt;)&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;
&lt;code&gt;docker stop&lt;/code&gt; takes 10 s, exit code 137&lt;/td&gt;
&lt;td&gt;Shell-form &lt;code&gt;CMD&lt;/code&gt;, &lt;code&gt;sh&lt;/code&gt; swallows SIGTERM&lt;/td&gt;
&lt;td&gt;Exec-form &lt;code&gt;CMD&lt;/code&gt;, or &lt;code&gt;exec&lt;/code&gt; in front of the last command&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;
&lt;code&gt;ValueError: invalid interpolation syntax&lt;/code&gt; from Alembic&lt;/td&gt;
&lt;td&gt;
&lt;code&gt;%&lt;/code&gt; in an encoded password&lt;/td&gt;
&lt;td&gt;
&lt;code&gt;.replace("%", "%%")&lt;/code&gt; in &lt;code&gt;env.py&lt;/code&gt;
&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;could not translate host name&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;
&lt;code&gt;@&lt;/code&gt;, &lt;code&gt;#&lt;/code&gt; or &lt;code&gt;/&lt;/code&gt; unencoded in the password&lt;/td&gt;
&lt;td&gt;URL-encode the password in &lt;code&gt;DATABASE_URL&lt;/code&gt;
&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Postgres 18 container keeps restarting&lt;/td&gt;
&lt;td&gt;Volume at &lt;code&gt;/var/lib/postgresql/data&lt;/code&gt;
&lt;/td&gt;
&lt;td&gt;Mount &lt;code&gt;/var/lib/postgresql&lt;/code&gt;
&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;
&lt;code&gt;/openapi.json&lt;/code&gt; still public&lt;/td&gt;
&lt;td&gt;Only &lt;code&gt;docs_url&lt;/code&gt; turned off&lt;/td&gt;
&lt;td&gt;&lt;code&gt;openapi_url=None&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Container killed under load&lt;/td&gt;
&lt;td&gt;Too many workers for the memory&lt;/td&gt;
&lt;td&gt;One process per container, more replicas&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;h2&gt;
  
  
  FAQ
&lt;/h2&gt;

&lt;h3&gt;
  
  
  Should I use Gunicorn with FastAPI?
&lt;/h3&gt;

&lt;p&gt;Not any more. Gunicorn was used to restart crashed Uvicorn workers. &lt;code&gt;fastapi run --workers N&lt;/code&gt; and &lt;code&gt;uvicorn --workers N&lt;/code&gt; do that themselves now, and FastAPI's official guide to server workers uses only those two commands. The old &lt;code&gt;uvicorn.workers&lt;/code&gt; module is deprecated in favour of the separate &lt;code&gt;uvicorn-worker&lt;/code&gt; package. Use Gunicorn only if your team already depends on its hooks.&lt;/p&gt;

&lt;h3&gt;
  
  
  What's the difference between &lt;code&gt;fastapi run&lt;/code&gt; and &lt;code&gt;uvicorn&lt;/code&gt;?
&lt;/h3&gt;

&lt;p&gt;&lt;code&gt;fastapi run&lt;/code&gt; is a thin wrapper around Uvicorn. It finds your app object, binds &lt;code&gt;0.0.0.0:8000&lt;/code&gt;, turns reload off and enables proxy headers. &lt;code&gt;uvicorn app.main:app --host 0.0.0.0 --port 8000&lt;/code&gt; gives the same server. Pick one and use it everywhere.&lt;/p&gt;

&lt;h3&gt;
  
  
  How many Uvicorn workers do I need?
&lt;/h3&gt;

&lt;p&gt;One per container when a platform or orchestrator runs replicas. On a single server, start with one worker per full CPU core and confirm the memory fits: each extra worker here added about 100 MB.&lt;/p&gt;

&lt;h3&gt;
  
  
  Is Uvicorn production ready?
&lt;/h3&gt;

&lt;p&gt;Yes. It's the server FastAPI's own docs use in production. Put a TLS-terminating proxy or platform edge in front of it and trust its headers as in Step 6.&lt;/p&gt;

&lt;h3&gt;
  
  
  How do I disable the docs in production?
&lt;/h3&gt;

&lt;p&gt;Pass &lt;code&gt;openapi_url=None&lt;/code&gt; to &lt;code&gt;FastAPI()&lt;/code&gt;. That turns off &lt;code&gt;/docs&lt;/code&gt;, &lt;code&gt;/redoc&lt;/code&gt; and &lt;code&gt;/openapi.json&lt;/code&gt; together. Use an environment variable, as in Step 1, so staging can keep them.&lt;/p&gt;

&lt;h3&gt;
  
  
  Why does my FastAPI app redirect to HTTP behind Nginx?
&lt;/h3&gt;

&lt;p&gt;The app doesn't trust the &lt;code&gt;X-Forwarded-Proto&lt;/code&gt; header from Nginx, so it thinks the request was plain HTTP. Send the header from Nginx and set &lt;code&gt;FORWARDED_ALLOW_IPS&lt;/code&gt; (Step 6).&lt;/p&gt;

&lt;h3&gt;
  
  
  Where should database migrations run?
&lt;/h3&gt;

&lt;p&gt;Before the new code serves requests: a Compose job gated with &lt;code&gt;service_completed_successfully&lt;/code&gt;, a CI step, or, with a single container, a start command that runs &lt;code&gt;alembic upgrade head&lt;/code&gt; and then &lt;code&gt;exec&lt;/code&gt;s the server. Not inside every worker's startup. &lt;a href="https://blog.hubfly.space/docker-compose-migration-job-service-completed-successfully?utm_source=devto&amp;amp;utm_campaign=how-to-deploy-fastapi-to-production" rel="noopener noreferrer"&gt;This post shows the job pattern in detail&lt;/a&gt;.&lt;/p&gt;

&lt;h3&gt;
  
  
  Should I use &lt;code&gt;async def&lt;/code&gt; or &lt;code&gt;def&lt;/code&gt; for endpoints?
&lt;/h3&gt;

&lt;p&gt;Use &lt;code&gt;async def&lt;/code&gt; when everything you await is async (an async database driver, &lt;code&gt;httpx.AsyncClient&lt;/code&gt;). Use &lt;code&gt;def&lt;/code&gt; for blocking libraries like the synchronous SQLAlchemy session here. FastAPI runs &lt;code&gt;def&lt;/code&gt; endpoints in a thread pool, so they don't block the server.&lt;/p&gt;

&lt;h2&gt;
  
  
  Go further on Hubfly space
&lt;/h2&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;Skip running Postgres yourself:&lt;/strong&gt; a &lt;a href="https://blog.hubfly.space/managed-postgresql-database-2-dollars-a-month?utm_source=devto&amp;amp;utm_campaign=how-to-deploy-fastapi-to-production" rel="noopener noreferrer"&gt;managed PostgreSQL database&lt;/a&gt; starts at about $2.02 a month (&lt;a href="https://www.hubfly.space/docs/databases/get-started/?ref=how-to-deploy-fastapi-to-production" rel="noopener noreferrer"&gt;docs&lt;/a&gt;).&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Deploy on every push:&lt;/strong&gt; trigger a redeploy from GitHub Actions with a &lt;a href="https://blog.hubfly.space/deploy-on-push-github-actions-webhook?utm_source=devto&amp;amp;utm_campaign=how-to-deploy-fastapi-to-production" rel="noopener noreferrer"&gt;deploy webhook&lt;/a&gt; (&lt;a href="https://www.hubfly.space/docs/deployment-pipelines/?ref=how-to-deploy-fastapi-to-production" rel="noopener noreferrer"&gt;docs&lt;/a&gt;).&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Scale out:&lt;/strong&gt; replicate the API container behind a load balancer when one process isn't enough (&lt;a href="https://www.hubfly.space/docs/load-balancers/?ref=how-to-deploy-fastapi-to-production" rel="noopener noreferrer"&gt;docs&lt;/a&gt;).&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;&lt;a href="https://hubfly.space/?ref=how-to-deploy-fastapi-to-production" rel="noopener noreferrer"&gt;&lt;strong&gt;Try it on Hubfly space&lt;/strong&gt;&lt;/a&gt;&lt;/p&gt;




&lt;p&gt;&lt;em&gt;By Octave · drafted with AI, reviewed by Octave · Last updated 9 November 2026&lt;/em&gt;&lt;/p&gt;

&lt;p&gt;&lt;em&gt;Originally published on the &lt;a href="https://blog.hubfly.space/how-to-deploy-fastapi-to-production?utm_source=devto&amp;amp;utm_campaign=how-to-deploy-fastapi-to-production" rel="noopener noreferrer"&gt;Hubfly space Journal&lt;/a&gt;.&lt;/em&gt;&lt;/p&gt;

</description>
      <category>fastapi</category>
      <category>python</category>
      <category>docker</category>
      <category>devops</category>
    </item>
    <item>
      <title>How to upgrade Postgres to a new major version in Docker</title>
      <dc:creator>octave Nkurunziza</dc:creator>
      <pubDate>Mon, 09 Nov 2026 08:22:02 +0000</pubDate>
      <link>https://dev.to/octave_nkurunziza_afb0512/how-to-upgrade-postgres-to-a-new-major-version-in-docker-2pjn</link>
      <guid>https://dev.to/octave_nkurunziza_afb0512/how-to-upgrade-postgres-to-a-new-major-version-in-docker-2pjn</guid>
      <description>&lt;p&gt;&lt;a href="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2F3804eyq5cpe4bfnviuyv.png" class="article-body-image-wrapper"&gt;&lt;img src="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2F3804eyq5cpe4bfnviuyv.png" alt="The old Postgres 16 container streams its data into a new Postgres 18 container with a fresh volume, while the old volume stays untouched for rollback" width="800" height="450"&gt;&lt;/a&gt;&lt;/p&gt;

&lt;p&gt;You can't upgrade Postgres to a new major version in Docker by changing the image tag. Each major version (16, 17, 18) stores data on disk in its own format, so &lt;code&gt;postgres:18&lt;/code&gt; refuses to start on a volume that &lt;code&gt;postgres:16&lt;/code&gt; created. This guide moves your data across the safe way: a new container and a new volume, a full copy with &lt;code&gt;pg_dumpall&lt;/code&gt;, a check that every row arrived, and an old volume you can roll back to in one line. For a typical app database it takes a few minutes, and your app is down only while the copy runs.&lt;/p&gt;

&lt;p&gt;&lt;a href="https://www.hubfly.space/?ref=upgrade-postgres-major-version-docker" rel="noopener noreferrer"&gt;Try it on Hubfly space&lt;/a&gt;: run Postgres in a container with a persistent volume.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Versions used:&lt;/strong&gt; PostgreSQL 16.15 → 18.6 with the official &lt;code&gt;postgres&lt;/code&gt; images, and Docker Compose v2 syntax. The same steps work for any jump, such as 14 → 17 or 15 → 18.&lt;/p&gt;

&lt;h2&gt;
  
  
  Why you can't just change the image tag
&lt;/h2&gt;

&lt;p&gt;If you edit &lt;code&gt;image: postgres:16&lt;/code&gt; to &lt;code&gt;image: postgres:18&lt;/code&gt; and restart, one of two things happens.&lt;/p&gt;

&lt;p&gt;With Postgres 17 or older on the new side, you get:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;FATAL:  database files are incompatible with server
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;With Postgres 18 there's a second surprise. The official image moved its data directory. Up to 17, you mount the volume at &lt;code&gt;/var/lib/postgresql/data&lt;/code&gt;. From 18, the image stores data in &lt;code&gt;/var/lib/postgresql/18/docker&lt;/code&gt; and expects the volume at &lt;code&gt;/var/lib/postgresql&lt;/code&gt;. If you keep the old mount, the container exits with a long message that starts like this:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;Error: in 18+, these Docker images are configured to store database data in a
       format which is compatible with "pg_ctlcluster" (specifically, using
       major-version-specific directory names).
       ...
       Counter to that, there appears to be PostgreSQL data in:
         /var/lib/postgresql/data (unused mount/volume)
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Some platforms keep reporting the service as started while it restarts in a loop, so check the logs, not just the status.&lt;/p&gt;

&lt;p&gt;Both errors protect your data. Nothing is lost yet. Don't delete the volume, and don't point a fresh Postgres 18 at an empty mount path and carry on: your app would connect to a blank database.&lt;/p&gt;

&lt;h2&gt;
  
  
  The plan to upgrade a Postgres major version in Docker
&lt;/h2&gt;

&lt;ol&gt;
&lt;li&gt;Run the new version &lt;strong&gt;next to&lt;/strong&gt; the old one, with its &lt;strong&gt;own&lt;/strong&gt; volume.&lt;/li&gt;
&lt;li&gt;Stop the app so nothing writes during the copy.&lt;/li&gt;
&lt;li&gt;Copy everything (roles, passwords, databases, extensions) with &lt;code&gt;pg_dumpall&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;Check row counts and rebuild planner statistics.&lt;/li&gt;
&lt;li&gt;Point the app at the new database. Keep the old volume until you're sure.&lt;/li&gt;
&lt;/ol&gt;

&lt;p&gt;This is a dump and restore. It's the simplest method and the one with the clearest rollback. For databases of hundreds of gigabytes, &lt;code&gt;pg_upgrade&lt;/code&gt; is faster; see the FAQ.&lt;/p&gt;

&lt;h2&gt;
  
  
  Step 1: Note what you have
&lt;/h2&gt;

&lt;p&gt;Start from a typical Compose file:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight yaml"&gt;&lt;code&gt;&lt;span class="na"&gt;services&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt;
  &lt;span class="na"&gt;db&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt;
    &lt;span class="na"&gt;image&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="s"&gt;postgres:16&lt;/span&gt;
    &lt;span class="na"&gt;environment&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt;
      &lt;span class="na"&gt;POSTGRES_PASSWORD&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="s"&gt;${POSTGRES_PASSWORD}&lt;/span&gt;
      &lt;span class="na"&gt;POSTGRES_DB&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="s"&gt;orders&lt;/span&gt;
    &lt;span class="na"&gt;volumes&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt;
      &lt;span class="pi"&gt;-&lt;/span&gt; &lt;span class="s"&gt;pgdata:/var/lib/postgresql/data&lt;/span&gt;

  &lt;span class="na"&gt;web&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt;
    &lt;span class="na"&gt;image&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="s"&gt;your-app:latest&lt;/span&gt;
    &lt;span class="na"&gt;environment&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt;
      &lt;span class="na"&gt;DATABASE_URL&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="s"&gt;postgres://postgres:${POSTGRES_PASSWORD}@db:5432/orders&lt;/span&gt;
    &lt;span class="na"&gt;depends_on&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt;
      &lt;span class="pi"&gt;-&lt;/span&gt; &lt;span class="s"&gt;db&lt;/span&gt;

&lt;span class="na"&gt;volumes&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt;
  &lt;span class="na"&gt;pgdata&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Record the version, the database size, the row counts of your biggest tables, and a checksum-style value you can compare later:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;docker compose &lt;span class="nb"&gt;exec &lt;/span&gt;db psql &lt;span class="nt"&gt;-U&lt;/span&gt; postgres &lt;span class="nt"&gt;-c&lt;/span&gt; &lt;span class="s2"&gt;"select version();"&lt;/span&gt;
docker compose &lt;span class="nb"&gt;exec &lt;/span&gt;db psql &lt;span class="nt"&gt;-U&lt;/span&gt; postgres &lt;span class="nt"&gt;-d&lt;/span&gt; orders &lt;span class="nt"&gt;-c&lt;/span&gt; &lt;span class="s2"&gt;"select pg_size_pretty(pg_database_size('orders'));"&lt;/span&gt;
docker compose &lt;span class="nb"&gt;exec &lt;/span&gt;db psql &lt;span class="nt"&gt;-U&lt;/span&gt; postgres &lt;span class="nt"&gt;-d&lt;/span&gt; orders &lt;span class="nt"&gt;-c&lt;/span&gt; &lt;span class="s2"&gt;"select 'orders', count(*) from orders union all select 'customers', count(*) from customers;"&lt;/span&gt;
docker compose &lt;span class="nb"&gt;exec &lt;/span&gt;db psql &lt;span class="nt"&gt;-U&lt;/span&gt; postgres &lt;span class="nt"&gt;-d&lt;/span&gt; orders &lt;span class="nt"&gt;-Atc&lt;/span&gt; &lt;span class="s2"&gt;"select sum(total_cents), max(id) from orders;"&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Also list the extensions you use. The new image must ship them too (the official image includes the standard contrib extensions like &lt;code&gt;citext&lt;/code&gt;, &lt;code&gt;pgcrypto&lt;/code&gt; and &lt;code&gt;pg_trgm&lt;/code&gt;; PostGIS or pgvector need their own images).&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;docker compose &lt;span class="nb"&gt;exec &lt;/span&gt;db psql &lt;span class="nt"&gt;-U&lt;/span&gt; postgres &lt;span class="nt"&gt;-d&lt;/span&gt; orders &lt;span class="nt"&gt;-c&lt;/span&gt; &lt;span class="s2"&gt;"select extname, extversion from pg_extension;"&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;&lt;code&gt;pg_dumpall&lt;/code&gt; copies roles and data, not server settings. Save anything you changed in &lt;code&gt;postgresql.conf&lt;/code&gt;, &lt;code&gt;pg_hba.conf&lt;/code&gt; or with &lt;code&gt;ALTER SYSTEM&lt;/code&gt;, so you can apply it to the new server:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;docker compose &lt;span class="nb"&gt;exec &lt;/span&gt;db psql &lt;span class="nt"&gt;-U&lt;/span&gt; postgres &lt;span class="nt"&gt;-c&lt;/span&gt; &lt;span class="s2"&gt;"select name, setting, source from pg_settings where source not in ('default', 'override', 'client');"&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Apply them on the new server with &lt;code&gt;ALTER SYSTEM SET …&lt;/code&gt; after Step 4.&lt;/p&gt;

&lt;p&gt;If you set &lt;code&gt;POSTGRES_USER&lt;/code&gt;, use that name wherever this guide says &lt;code&gt;-U postgres&lt;/code&gt;. The expected error in Step 4 then names that role instead.&lt;/p&gt;

&lt;h2&gt;
  
  
  Step 2: Take a file backup first
&lt;/h2&gt;

&lt;p&gt;Before anything else, write a full backup to your machine. This is your safety net if you mistype something later.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;docker compose &lt;span class="nb"&gt;exec&lt;/span&gt; &lt;span class="nt"&gt;-T&lt;/span&gt; db pg_dumpall &lt;span class="nt"&gt;-U&lt;/span&gt; postgres &lt;span class="o"&gt;&amp;gt;&lt;/span&gt; backup-pg16.sql
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The &lt;code&gt;-T&lt;/code&gt; flag matters. It turns off Docker's pseudo-terminal, which otherwise can mangle the output when you redirect it to a file. Many guides use &lt;code&gt;docker exec -it&lt;/code&gt; here; drop the &lt;code&gt;t&lt;/code&gt;.&lt;/p&gt;

&lt;p&gt;The file holds all your data and every password hash. Run &lt;code&gt;chmod 600 backup-pg16.sql&lt;/code&gt;, keep it out of git, and delete it once the upgrade is done.&lt;/p&gt;

&lt;p&gt;For a sense of scale: an 86 MB database with a million rows produced a 47 MB SQL file in 3.6 seconds on a small server with half a CPU core. Plan for seconds per gigabyte on a fast machine and longer on a busy one.&lt;/p&gt;

&lt;p&gt;&lt;a href="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Fv1fxb6o4addm07cacubu.png" class="article-body-image-wrapper"&gt;&lt;img src="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Fv1fxb6o4addm07cacubu.png" alt="The Postgres 16 server before the upgrade: version 16.15, an 86 MB database with 1,000,000 orders, the citext extension, and a 47 MB backup written in 3.6 seconds" width="800" height="228"&gt;&lt;/a&gt;&lt;/p&gt;

&lt;h2&gt;
  
  
  Step 3: Add the new database next to the old one
&lt;/h2&gt;

&lt;p&gt;Add a second service with the new image and a &lt;strong&gt;new&lt;/strong&gt; volume, mounted at the Postgres 18 path:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight yaml"&gt;&lt;code&gt;  &lt;span class="na"&gt;db18&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt;
    &lt;span class="na"&gt;image&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="s"&gt;postgres:18&lt;/span&gt;
    &lt;span class="na"&gt;environment&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt;
      &lt;span class="na"&gt;POSTGRES_PASSWORD&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="s"&gt;${POSTGRES_PASSWORD}&lt;/span&gt;
    &lt;span class="na"&gt;volumes&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt;
      &lt;span class="pi"&gt;-&lt;/span&gt; &lt;span class="s"&gt;pgdata18:/var/lib/postgresql&lt;/span&gt;

&lt;span class="na"&gt;volumes&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt;
  &lt;span class="na"&gt;pgdata&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt;
  &lt;span class="na"&gt;pgdata18&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Use the same &lt;code&gt;POSTGRES_USER&lt;/code&gt; as the old service if you set one. Don't set &lt;code&gt;POSTGRES_DB&lt;/code&gt; here: the dump creates your databases, and a pre-created one only adds an "already exists" error.&lt;/p&gt;

&lt;p&gt;Start only the new database:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;docker compose up &lt;span class="nt"&gt;-d&lt;/span&gt; db18
docker compose logs db18 | &lt;span class="nb"&gt;tail&lt;/span&gt; &lt;span class="nt"&gt;-5&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Wait for &lt;code&gt;database system is ready to accept connections&lt;/code&gt;.&lt;/p&gt;

&lt;p&gt;&lt;a href="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2F5jlai9i6ay2crk4mvnbw.png" class="article-body-image-wrapper"&gt;&lt;img src="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2F5jlai9i6ay2crk4mvnbw.png" alt="The new Postgres 18 container's volume, mounted at /var/lib/postgresql" width="798" height="250"&gt;&lt;/a&gt;&lt;/p&gt;

&lt;h2&gt;
  
  
  Step 4: Stop the app and copy the data
&lt;/h2&gt;

&lt;p&gt;Stop everything that writes to the database. Writes that land after the copy starts won't be in the new database.&lt;br&gt;
&lt;/p&gt;

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

&lt;/div&gt;



&lt;p&gt;Now stream the dump from the old container straight into the new one, with no file in between. Run it inside the new container so the newer Postgres 18 client does the reading and writing:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;docker compose &lt;span class="nb"&gt;exec&lt;/span&gt; &lt;span class="nt"&gt;-T&lt;/span&gt; db18 sh &lt;span class="nt"&gt;-c&lt;/span&gt; &lt;span class="se"&gt;\&lt;/span&gt;
  &lt;span class="s1"&gt;'PGPASSWORD="$POSTGRES_PASSWORD" pg_dumpall -h db -U postgres | psql -U postgres -X -q -o /dev/null'&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The single quotes matter: &lt;code&gt;$POSTGRES_PASSWORD&lt;/code&gt; is read inside the new container, which has the same password as the old one, so the secret never passes through your shell.&lt;/p&gt;

&lt;p&gt;You'll see one error, and it's fine:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;ERROR:  role "postgres" already exists
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The dump recreates every role, including the superuser that the new container already made. Anything else in the output deserves a look.&lt;/p&gt;

&lt;p&gt;Don't add &lt;code&gt;-v ON_ERROR_STOP=1&lt;/code&gt; to this command. It sounds safer, but it stops at that harmless first error, before any of your data is copied, and &lt;code&gt;pg_dumpall&lt;/code&gt; then exits with &lt;code&gt;pg_dump failed on database "template1"&lt;/code&gt;.&lt;/p&gt;

&lt;p&gt;The 86 MB database took about 7 seconds to stream from Postgres 16 into Postgres 18 between two small containers. That's your downtime, plus a restart.&lt;/p&gt;

&lt;p&gt;&lt;a href="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Fvdkbxtsl7kha8vbr263c.png" class="article-body-image-wrapper"&gt;&lt;img src="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Fvdkbxtsl7kha8vbr263c.png" alt="The copy finished on Postgres 18.6 in 7.4 seconds with the single expected error" width="800" height="138"&gt;&lt;/a&gt;&lt;/p&gt;

&lt;h2&gt;
  
  
  Step 5: Check the copy and rebuild statistics
&lt;/h2&gt;

&lt;p&gt;Run the same counts and the same sum against the new database:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;docker compose &lt;span class="nb"&gt;exec &lt;/span&gt;db18 psql &lt;span class="nt"&gt;-U&lt;/span&gt; postgres &lt;span class="nt"&gt;-d&lt;/span&gt; orders &lt;span class="nt"&gt;-c&lt;/span&gt; &lt;span class="s2"&gt;"select 'orders', count(*) from orders union all select 'customers', count(*) from customers;"&lt;/span&gt;
docker compose &lt;span class="nb"&gt;exec &lt;/span&gt;db18 psql &lt;span class="nt"&gt;-U&lt;/span&gt; postgres &lt;span class="nt"&gt;-d&lt;/span&gt; orders &lt;span class="nt"&gt;-Atc&lt;/span&gt; &lt;span class="s2"&gt;"select sum(total_cents), max(id) from orders;"&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Both must match what you wrote down in Step 1. Sequences come across too, so new rows won't collide with old IDs.&lt;/p&gt;

&lt;p&gt;Check the extensions again:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;docker compose &lt;span class="nb"&gt;exec &lt;/span&gt;db18 psql &lt;span class="nt"&gt;-U&lt;/span&gt; postgres &lt;span class="nt"&gt;-d&lt;/span&gt; orders &lt;span class="nt"&gt;-c&lt;/span&gt; &lt;span class="s2"&gt;"select extname, extversion from pg_extension;"&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Don't be surprised if the versions changed. The dump says "create this extension", not "create version 1.6", so the new server installs its own default. &lt;code&gt;citext&lt;/code&gt; went from 1.6 on Postgres 16 to 1.8 on Postgres 18. That's normal, but if your app pins an extension version, read its changelog.&lt;/p&gt;

&lt;p&gt;Next, rebuild the planner statistics. &lt;code&gt;pg_dumpall&lt;/code&gt; doesn't copy the statistics Postgres uses to pick query plans (Postgres 18 added a &lt;code&gt;--statistics&lt;/code&gt; option, but it's off by default), so the new database starts without them. Autovacuum usually analyzes fresh tables within a minute or so, but on a big or busy database it can lag, and until then queries can pick bad plans. Don't wait for it:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;docker compose &lt;span class="nb"&gt;exec &lt;/span&gt;db18 vacuumdb &lt;span class="nt"&gt;-U&lt;/span&gt; postgres &lt;span class="nt"&gt;--all&lt;/span&gt; &lt;span class="nt"&gt;--analyze-in-stages&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;&lt;code&gt;--analyze-in-stages&lt;/code&gt; produces rough statistics fast and then refines them, so you can bring the app back sooner. It took under 3 seconds for the 86 MB database.&lt;/p&gt;

&lt;h2&gt;
  
  
  Step 6: Switch the app over
&lt;/h2&gt;

&lt;p&gt;The cleanest switch is to make &lt;code&gt;db&lt;/code&gt; the new database, so the hostname in &lt;code&gt;DATABASE_URL&lt;/code&gt; stays the same. Edit the &lt;code&gt;db&lt;/code&gt; service:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight yaml"&gt;&lt;code&gt;  &lt;span class="na"&gt;db&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt;
    &lt;span class="na"&gt;image&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="s"&gt;postgres:18&lt;/span&gt;
    &lt;span class="na"&gt;environment&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt;
      &lt;span class="na"&gt;POSTGRES_PASSWORD&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="s"&gt;${POSTGRES_PASSWORD}&lt;/span&gt;
    &lt;span class="na"&gt;volumes&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt;
      &lt;span class="pi"&gt;-&lt;/span&gt; &lt;span class="s"&gt;pgdata18:/var/lib/postgresql&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Delete the &lt;code&gt;db18&lt;/code&gt; block from the file in the same edit (keep both &lt;code&gt;pgdata&lt;/code&gt; and &lt;code&gt;pgdata18&lt;/code&gt; under &lt;code&gt;volumes:&lt;/code&gt;). Then stop the temporary service, recreate &lt;code&gt;db&lt;/code&gt;, and start the app:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;docker compose stop db18
docker compose &lt;span class="nb"&gt;rm&lt;/span&gt; &lt;span class="nt"&gt;-f&lt;/span&gt; db18
docker compose up &lt;span class="nt"&gt;-d&lt;/span&gt; db
docker compose up &lt;span class="nt"&gt;-d&lt;/span&gt; web
docker compose &lt;span class="nb"&gt;exec &lt;/span&gt;db psql &lt;span class="nt"&gt;-U&lt;/span&gt; postgres &lt;span class="nt"&gt;-c&lt;/span&gt; &lt;span class="s2"&gt;"select version();"&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Never start &lt;code&gt;db18&lt;/code&gt; again: it uses the same volume as the new &lt;code&gt;db&lt;/code&gt;, and two servers must not share one data directory.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;To roll back&lt;/strong&gt;, put &lt;code&gt;db&lt;/code&gt; back to &lt;code&gt;image: postgres:16&lt;/code&gt; with &lt;code&gt;pgdata:/var/lib/postgresql/data&lt;/code&gt; and run &lt;code&gt;docker compose up -d db&lt;/code&gt;. The old volume was never touched. Anything written after the switch is only in the new database, so roll back early or not at all.&lt;/p&gt;

&lt;p&gt;After a week of normal traffic, remove the old volume. &lt;code&gt;docker volume ls&lt;/code&gt; shows its full name with the project prefix:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;docker volume &lt;span class="nb"&gt;ls
&lt;/span&gt;docker volume &lt;span class="nb"&gt;rm &lt;/span&gt;yourproject_pgdata
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Never run &lt;code&gt;docker compose down -v&lt;/code&gt; during an upgrade. The &lt;code&gt;-v&lt;/code&gt; deletes every named volume in the file, old and new.&lt;/p&gt;

&lt;h2&gt;
  
  
  Do it on Hubfly space
&lt;/h2&gt;

&lt;p&gt;The same plan works on a Hubfly space Cell project, with no Docker install of your own.&lt;/p&gt;

&lt;p&gt;&lt;a href="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2F2rs4ombnf925xczrc4z1.png" class="article-body-image-wrapper"&gt;&lt;img src="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2F2rs4ombnf925xczrc4z1.png" alt="The old and new database containers running side by side in one project" width="442" height="249"&gt;&lt;/a&gt;&lt;/p&gt;

&lt;ol&gt;
&lt;li&gt;In your project, create a second container from the &lt;code&gt;postgres:18&lt;/code&gt; image with the same &lt;code&gt;POSTGRES_PASSWORD&lt;/code&gt;, and add a new volume mounted at &lt;code&gt;/var/lib/postgresql&lt;/code&gt;. A Compose file with both services works too: paste it into &lt;strong&gt;Create → Compose Stack&lt;/strong&gt;.&lt;/li&gt;
&lt;li&gt;Open the old database container's &lt;strong&gt;Network&lt;/strong&gt; tab and copy its &lt;strong&gt;Private network alias&lt;/strong&gt;. It looks like &lt;code&gt;db-01f8845a.eunorth.hubfly.internal&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;Open the new container's &lt;strong&gt;Console&lt;/strong&gt; tab and run the Step 4 copy with that alias in place of &lt;code&gt;db&lt;/code&gt;:
&lt;/li&gt;
&lt;/ol&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;&lt;span class="nv"&gt;PGPASSWORD&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="s2"&gt;"&lt;/span&gt;&lt;span class="nv"&gt;$POSTGRES_PASSWORD&lt;/span&gt;&lt;span class="s2"&gt;"&lt;/span&gt; pg_dumpall &lt;span class="nt"&gt;-h&lt;/span&gt; db-01f8845a.eunorth.hubfly.internal &lt;span class="nt"&gt;-U&lt;/span&gt; postgres | psql &lt;span class="nt"&gt;-U&lt;/span&gt; postgres &lt;span class="nt"&gt;-X&lt;/span&gt; &lt;span class="nt"&gt;-q&lt;/span&gt; &lt;span class="nt"&gt;-o&lt;/span&gt; /dev/null
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;ol&gt;
&lt;li&gt;In the same Console, run the Step 5 checks and &lt;code&gt;vacuumdb -U postgres --all --analyze-in-stages&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;Point your app's &lt;code&gt;DATABASE_URL&lt;/code&gt; at the new container's alias and redeploy the app.&lt;/li&gt;
&lt;/ol&gt;

&lt;p&gt;Volumes on Hubfly space keep their data across redeploys, but there are no volume snapshots, so the old volume is your rollback. Keep it until you're sure. A Standard volume costs $0.00001536 per GB-hour (about $0.011 per GB a month); Balanced costs 1.5× that and High Performance 2×. Keeping a 10 GB Balanced volume for a week costs about 4 cents. A second small database container (0.5 vCPU, 512 MB, Dedicated) costs about $0.003 an hour while it runs, so an upgrade afternoon costs pennies. &lt;a href="https://www.hubfly.space/docs/volumes/?ref=upgrade-postgres-major-version-docker" rel="noopener noreferrer"&gt;Read how volumes work&lt;/a&gt;.&lt;/p&gt;

&lt;h2&gt;
  
  
  What can go wrong
&lt;/h2&gt;

&lt;p&gt;&lt;strong&gt;&lt;code&gt;FATAL: database files are incompatible with server&lt;/code&gt;.&lt;/strong&gt; You started a newer Postgres on an old data directory. Change the image back, then follow the steps above.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;&lt;code&gt;there appears to be PostgreSQL data in: /var/lib/postgresql/data (unused mount/volume)&lt;/code&gt;.&lt;/strong&gt; You're on &lt;code&gt;postgres:18&lt;/code&gt; with the old mount path. For a fresh 18 volume, mount it at &lt;code&gt;/var/lib/postgresql&lt;/code&gt;. Don't "fix" it by setting &lt;code&gt;PGDATA&lt;/code&gt; to point 18 at your 16 data: the files are still in the 16 format.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;The restore stops right away with &lt;code&gt;role "postgres" already exists&lt;/code&gt;.&lt;/strong&gt; You added &lt;code&gt;ON_ERROR_STOP&lt;/code&gt;. Remove it; that error is expected.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;&lt;code&gt;invalid command \restrict&lt;/code&gt;.&lt;/strong&gt; Dumps from recent Postgres patch releases (16.15's dump starts with one) contain &lt;code&gt;\restrict&lt;/code&gt; lines that older &lt;code&gt;psql&lt;/code&gt; clients don't understand. Restore with the &lt;code&gt;psql&lt;/code&gt; inside the new container, which is new enough to read it.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;&lt;code&gt;password authentication failed&lt;/code&gt; for one app user after the upgrade.&lt;/strong&gt; That role probably still has an old MD5 password hash, common when the database first ran on Postgres 13 or older. The dump copies the hash as it is. The official images use &lt;code&gt;scram-sha-256&lt;/code&gt; for network logins, which can't check MD5 hashes, and Postgres 18 deprecates MD5 passwords. Find those roles and set each password again from &lt;code&gt;psql&lt;/code&gt;, which keeps it out of your shell history:&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="n"&gt;rolname&lt;/span&gt; &lt;span class="k"&gt;from&lt;/span&gt; &lt;span class="n"&gt;pg_authid&lt;/span&gt; &lt;span class="k"&gt;where&lt;/span&gt; &lt;span class="n"&gt;rolpassword&lt;/span&gt; &lt;span class="k"&gt;like&lt;/span&gt; &lt;span class="s1"&gt;'md5%'&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="err"&gt;\&lt;/span&gt;&lt;span class="n"&gt;password&lt;/span&gt; &lt;span class="n"&gt;legacy_report&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;&lt;strong&gt;The app is slow right after the switch.&lt;/strong&gt; You skipped Step 5's &lt;code&gt;vacuumdb --analyze-in-stages&lt;/code&gt;. Run it now.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;An extension shows a different version.&lt;/strong&gt; Expected: the new server installs its own default version (&lt;code&gt;citext&lt;/code&gt; 1.6 → 1.8 in this upgrade). Check the extension's changelog if your app depends on a specific version.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;&lt;code&gt;extension "vector" is not available&lt;/code&gt;.&lt;/strong&gt; The plain &lt;code&gt;postgres&lt;/code&gt; image doesn't include that extension. Use an image that has it, such as &lt;code&gt;pgvector/pgvector:pg18&lt;/code&gt;, for the new service.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Disk fills up during the copy.&lt;/strong&gt; You need room for both volumes at once. The backup file from Step 2 needs space too, so write it to a different disk if space is tight.&lt;/p&gt;

&lt;h2&gt;
  
  
  FAQ
&lt;/h2&gt;

&lt;p&gt;&lt;strong&gt;How do I upgrade Postgres in Docker without losing data?&lt;/strong&gt;&lt;br&gt;
Run the new version in a second container with its own volume, copy everything with &lt;code&gt;pg_dumpall&lt;/code&gt; piped into &lt;code&gt;psql&lt;/code&gt;, check row counts, then switch the app. The old volume stays untouched until you delete it.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Can I just change the image tag from postgres:16 to postgres:18?&lt;/strong&gt;&lt;br&gt;
No. Major versions use different on-disk formats, so the new server refuses to start. Minor updates within one major version, like 16.10 to 16.15, are safe in almost all cases: change the tag and restart. Read the release notes for any REINDEX steps, and pin the Debian variant you already run (today's &lt;code&gt;postgres:16&lt;/code&gt; is built on Debian trixie, so &lt;code&gt;postgres:16-trixie&lt;/code&gt;) so a base-image change doesn't change collations under you.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Should I mount /var/lib/postgresql or /var/lib/postgresql/data?&lt;/strong&gt;&lt;br&gt;
For &lt;code&gt;postgres:18&lt;/code&gt; and newer, mount &lt;code&gt;/var/lib/postgresql&lt;/code&gt;. For 17 and older, mount &lt;code&gt;/var/lib/postgresql/data&lt;/code&gt;.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Is pg_upgrade faster than pg_dumpall in Docker?&lt;/strong&gt;&lt;br&gt;
Yes, for big databases. &lt;code&gt;pg_upgrade --link&lt;/code&gt; reuses the data files instead of copying rows, but it needs both versions' binaries in one container, and both clusters must have the same data-checksum setting. Postgres 18 turns checksums on by default for new clusters, so if the old one has none, create the new one with &lt;code&gt;--no-data-checksums&lt;/code&gt;. For databases under a few tens of gigabytes, dump and restore is simpler and the downtime is short.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;How long does the upgrade take?&lt;/strong&gt;&lt;br&gt;
Mostly the time to copy your data. An 86 MB database streamed from 16 into 18 in about 7 seconds on two small containers; plan for minutes per 10 GB on typical cloud disks, and time a test run on a copy if downtime matters.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Can I upgrade from 14 straight to 18?&lt;/strong&gt;&lt;br&gt;
Yes. &lt;code&gt;pg_dumpall&lt;/code&gt; output from an older version restores into a newer one, so you can skip versions. Use the newest client, which is the one in the new container.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Can I do this with zero downtime?&lt;/strong&gt;&lt;br&gt;
Not with a dump. For near-zero downtime, use logical replication from old to new and switch once they're in sync. That takes more setup and is worth it only if a few minutes of downtime is a real problem.&lt;/p&gt;

&lt;h2&gt;
  
  
  Go further on Hubfly space
&lt;/h2&gt;

&lt;ul&gt;
&lt;li&gt;Add a health check so your app waits until the new database accepts connections: &lt;a href="https://blog.hubfly.space/docker-health-checks-postgres-redis?utm_source=devto&amp;amp;utm_campaign=upgrade-postgres-major-version-docker" rel="noopener noreferrer"&gt;Docker health checks that catch real problems&lt;/a&gt;.&lt;/li&gt;
&lt;li&gt;If queries feel slower after the switch, find the culprits: &lt;a href="https://blog.hubfly.space/find-fix-slow-postgresql-queries?utm_source=devto&amp;amp;utm_campaign=upgrade-postgres-major-version-docker" rel="noopener noreferrer"&gt;How to find and fix slow PostgreSQL queries&lt;/a&gt;.&lt;/li&gt;
&lt;li&gt;Don't want to run upgrades yourself? &lt;a href="https://blog.hubfly.space/managed-postgresql-database-2-dollars-a-month?utm_source=devto&amp;amp;utm_campaign=upgrade-postgres-major-version-docker" rel="noopener noreferrer"&gt;Get a managed PostgreSQL database for about $2 a month&lt;/a&gt;, or read how &lt;a href="https://www.hubfly.space/docs/volumes/?ref=upgrade-postgres-major-version-docker" rel="noopener noreferrer"&gt;volumes work on Hubfly space&lt;/a&gt;.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;&lt;a href="https://www.hubfly.space/?ref=upgrade-postgres-major-version-docker" rel="noopener noreferrer"&gt;&lt;strong&gt;Try it on Hubfly space →&lt;/strong&gt;&lt;/a&gt;: deploy &lt;code&gt;postgres:18&lt;/code&gt; with a persistent volume in a few clicks.&lt;/p&gt;




&lt;p&gt;&lt;em&gt;By Octave · drafted with AI, tested on Hubfly · Last updated 8 November 2026&lt;/em&gt;&lt;/p&gt;

&lt;p&gt;&lt;em&gt;Originally published on the &lt;a href="https://blog.hubfly.space/upgrade-postgres-major-version-docker?utm_source=devto&amp;amp;utm_campaign=upgrade-postgres-major-version-docker" rel="noopener noreferrer"&gt;Hubfly space Journal&lt;/a&gt;.&lt;/em&gt;&lt;/p&gt;

</description>
      <category>postgres</category>
      <category>docker</category>
      <category>database</category>
      <category>devops</category>
    </item>
    <item>
      <title>How to allow SSH from a specific IP only (without lockouts)</title>
      <dc:creator>octave Nkurunziza</dc:creator>
      <pubDate>Sat, 07 Nov 2026 12:09:42 +0000</pubDate>
      <link>https://dev.to/octave_nkurunziza_afb0512/how-to-allow-ssh-from-a-specific-ip-only-without-lockouts-d3f</link>
      <guid>https://dev.to/octave_nkurunziza_afb0512/how-to-allow-ssh-from-a-specific-ip-only-without-lockouts-d3f</guid>
      <description>&lt;p&gt;&lt;a href="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2F4982pp16f2wb37kzuazz.png" class="article-body-image-wrapper"&gt;&lt;img src="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2F4982pp16f2wb37kzuazz.png" alt="Two laptops try to reach a server on port 22; the firewall lets the one at the allowed IP through and silently drops the other" width="800" height="425"&gt;&lt;/a&gt;&lt;/p&gt;

&lt;p&gt;An SSH port open to the whole internet gets password guesses all day. The simplest fix is to allow SSH from a specific IP only, so the server answers your address and nobody else's. This guide does that with ufw on Ubuntu, checks it the right way, and adds a timer that reopens the door if you get it wrong. You also get a second lock inside SSH itself, and a plan for the day your home IP changes.&lt;/p&gt;

&lt;p&gt;&lt;a href="https://www.hubfly.space/?ref=allow-ssh-from-specific-ip-only" rel="noopener noreferrer"&gt;&lt;strong&gt;Try it on Hubfly space →&lt;/strong&gt;&lt;/a&gt;: run a Linux VM with root access and a firewall in front of it.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Versions used:&lt;/strong&gt; Ubuntu 24.04, ufw 0.36.2, OpenSSH 9.6p1. You need an SSH session as a user with sudo (&lt;code&gt;deploy&lt;/code&gt; below; use your own user name).&lt;/p&gt;

&lt;h2&gt;
  
  
  Step 1: Find the IP you connect from
&lt;/h2&gt;

&lt;p&gt;Don't guess it from a "what is my IP" site on another network. Ask the server, from the SSH session you already have:&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;echo&lt;/span&gt; &lt;span class="s2"&gt;"&lt;/span&gt;&lt;span class="nv"&gt;$SSH_CLIENT&lt;/span&gt;&lt;span class="s2"&gt;"&lt;/span&gt; | &lt;span class="nb"&gt;cut&lt;/span&gt; &lt;span class="nt"&gt;-d&lt;/span&gt;&lt;span class="s1"&gt;' '&lt;/span&gt; &lt;span class="nt"&gt;-f1&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;





&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;203.0.113.24
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;That's the address the server sees, which is the one the rule has to match. If it's an IPv6 address, use that address in the rules below instead.&lt;/p&gt;

&lt;p&gt;If you connect from more than one place (home, office, a VPN), write all of them down now.&lt;/p&gt;

&lt;p&gt;On a Hubfly space Box or any server behind a port mapping, check that this address really is yours. If it isn't, the server can't tell visitors apart by IP, so set the allowlist in the provider's firewall instead (see the Box section below) and skip Step 7.&lt;/p&gt;

&lt;h2&gt;
  
  
  Step 2: Look at the rules you already have
&lt;/h2&gt;

&lt;p&gt;Skip this step and the allowlist can do nothing at all.&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;sudo &lt;/span&gt;ufw status numbered
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;If it only says &lt;code&gt;Status: inactive&lt;/code&gt;, the firewall is off. Run &lt;code&gt;sudo ufw show added&lt;/code&gt; to list the rules that will load when you turn it on, and skip the default-policy check below (Step 4 sets it).&lt;/p&gt;

&lt;p&gt;If you see a line like this, an old rule already lets everyone in:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;[ 1] 22/tcp                     ALLOW IN    203.0.113.24
[ 2] 22/tcp                     ALLOW IN    Anywhere
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;ufw checks rules from the top and stops at the first match. Any connection to port 22 matches rule 2, so your new IP rule changes nothing. A setup script or an earlier &lt;code&gt;sudo ufw allow ssh&lt;/code&gt; often leaves this behind (it may be listed as &lt;code&gt;OpenSSH&lt;/code&gt; instead of &lt;code&gt;22/tcp&lt;/code&gt;). You'll delete it in Step 5, after the new rule is in place.&lt;/p&gt;

&lt;p&gt;&lt;a href="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2F0yneaerolrmwap1cagez.png" class="article-body-image-wrapper"&gt;&lt;img src="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2F0yneaerolrmwap1cagez.png" alt="ufw rule order: a leftover ALLOW Anywhere rule lets everyone in, a DENY above your ALLOW locks you out, and a single ALLOW from your IP plus default deny is correct" width="800" height="380"&gt;&lt;/a&gt;&lt;/p&gt;

&lt;p&gt;Also check the default policy. It has to be deny for incoming traffic:&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;sudo &lt;/span&gt;ufw status verbose | &lt;span class="nb"&gt;grep &lt;/span&gt;Default
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;





&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;Default: deny (incoming), allow (outgoing), disabled (routed)
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;h2&gt;
  
  
  Step 3: Set a safety net before you change anything
&lt;/h2&gt;

&lt;p&gt;If you make a mistake, the firewall should switch itself off after 5 minutes. Cache your sudo password first, so the background job doesn't sit waiting for it:&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;sudo&lt;/span&gt; &lt;span class="nt"&gt;-v&lt;/span&gt;
&lt;span class="nb"&gt;nohup sudo &lt;/span&gt;sh &lt;span class="nt"&gt;-c&lt;/span&gt; &lt;span class="s1"&gt;'sleep 300; ufw disable'&lt;/span&gt; &lt;span class="o"&gt;&amp;gt;&lt;/span&gt;/dev/null 2&amp;gt;&amp;amp;1 &amp;amp;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Keep the &lt;code&gt;nohup&lt;/code&gt;. Without it, a background job started from an interactive SSH session is killed when you log out, which is exactly when you'd need it.&lt;/p&gt;

&lt;p&gt;To cancel the timer once everything works, kill the shell that runs it, not the &lt;code&gt;sleep&lt;/code&gt;:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;&lt;span class="nb"&gt;sudo &lt;/span&gt;pkill &lt;span class="nt"&gt;-f&lt;/span&gt; &lt;span class="s1"&gt;'^sh -c sleep 300'&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The terminal prints &lt;code&gt;Terminated&lt;/code&gt;: that's the timer stopping. Don't kill only the &lt;code&gt;sleep&lt;/code&gt;. That ends the wait early, and the shell then runs &lt;code&gt;ufw disable&lt;/code&gt; right away.&lt;/p&gt;

&lt;h2&gt;
  
  
  Step 4: Allow SSH from a specific IP only
&lt;/h2&gt;



&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;&lt;span class="nb"&gt;sudo &lt;/span&gt;ufw default deny incoming
&lt;span class="nb"&gt;sudo &lt;/span&gt;ufw default allow outgoing
&lt;span class="nb"&gt;sudo &lt;/span&gt;ufw allow from 203.0.113.24 to any port 22 proto tcp
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Add one &lt;code&gt;allow from&lt;/code&gt; line per address from Step 1. For a range, use CIDR notation, and check how big it is: &lt;code&gt;10.0.0.0/30&lt;/code&gt; sounds like one address but covers four (&lt;code&gt;.0&lt;/code&gt; to &lt;code&gt;.3&lt;/code&gt;), so a neighbour at &lt;code&gt;.3&lt;/code&gt; gets in too.&lt;/p&gt;

&lt;p&gt;If SSH listens on another port, use that number. A rule for 22 won't help you on 2222.&lt;/p&gt;

&lt;p&gt;If the firewall isn't on yet, turn it on:&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;sudo &lt;/span&gt;ufw &lt;span class="nb"&gt;enable&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;





&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;Command may disrupt existing ssh connections. Proceed with operation (y|n)? y
Firewall is active and enabled on system startup
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;h2&gt;
  
  
  Step 5: Remove the rule that lets everyone in
&lt;/h2&gt;

&lt;p&gt;Delete the old open rule from Step 2 by its text (use &lt;code&gt;sudo ufw delete allow OpenSSH&lt;/code&gt; if it's listed that way):&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;sudo &lt;/span&gt;ufw delete allow 22/tcp
&lt;span class="nb"&gt;sudo &lt;/span&gt;ufw status numbered
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;





&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;[ 1] 22/tcp                     ALLOW IN    203.0.113.24
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;You don't need an explicit deny, because the default policy already drops everything else. If you add one anyway, it must come after your allow rule. A deny that comes first blocks you too. If that already happened, move your allow rule to the top:&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;sudo &lt;/span&gt;ufw delete allow from 203.0.113.24 to any port 22 proto tcp
&lt;span class="nb"&gt;sudo &lt;/span&gt;ufw insert 1 allow from 203.0.113.24 to any port 22 proto tcp
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;h2&gt;
  
  
  Step 6: Test from a new terminal, then from somewhere else
&lt;/h2&gt;

&lt;p&gt;Your current session proves nothing. A connection that was open before you enabled the firewall keeps working, even from a blocked address. Open a &lt;strong&gt;new&lt;/strong&gt; terminal and connect again:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;ssh deploy@your-server
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Then try from an address that should be blocked, such as your phone's hotspot:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;ssh: connect to host your-server port 22: Connection timed out
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;A timeout is what &lt;code&gt;deny&lt;/code&gt; looks like: the server drops the packets and says nothing. If you'd rather see an instant &lt;code&gt;Connection refused&lt;/code&gt; while you debug, use &lt;code&gt;sudo ufw reject 22/tcp&lt;/code&gt; instead of &lt;code&gt;deny&lt;/code&gt;. Both keep the connection out.&lt;/p&gt;

&lt;p&gt;When both tests behave, cancel the safety net from Step 3.&lt;/p&gt;

&lt;h2&gt;
  
  
  Step 7: Add a second lock inside SSH
&lt;/h2&gt;

&lt;p&gt;A firewall rule is one typo away from being wide open. SSH can check the source address too. Create a small config file:&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;echo&lt;/span&gt; &lt;span class="s1"&gt;'AllowUsers deploy@203.0.113.24'&lt;/span&gt; | &lt;span class="nb"&gt;sudo tee&lt;/span&gt; /etc/ssh/sshd_config.d/10-allowlist.conf
&lt;span class="nb"&gt;sudo &lt;/span&gt;sshd &lt;span class="nt"&gt;-t&lt;/span&gt; &lt;span class="o"&gt;&amp;amp;&amp;amp;&lt;/span&gt; &lt;span class="nb"&gt;sudo &lt;/span&gt;systemctl reload ssh
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;&lt;code&gt;sshd -t&lt;/code&gt; checks the config before you apply it. On Ubuntu the service is &lt;code&gt;ssh&lt;/code&gt;, not &lt;code&gt;sshd&lt;/code&gt;.&lt;/p&gt;

&lt;p&gt;Keep this session open: a reload doesn't close it. Log in again from a &lt;strong&gt;new&lt;/strong&gt; terminal before you close anything. If the new login fails, undo it from the session you still have:&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;sudo rm&lt;/span&gt; /etc/ssh/sshd_config.d/10-allowlist.conf &lt;span class="o"&gt;&amp;amp;&amp;amp;&lt;/span&gt; &lt;span class="nb"&gt;sudo &lt;/span&gt;systemctl reload ssh
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Once it works, a login from any other address fails even if the firewall lets it through, and the server log says why:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;User deploy from 198.51.100.7 not allowed because not listed in AllowUsers
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;&lt;code&gt;AllowUsers&lt;/code&gt; lists who may log in at all, so add every account you use, each with its address.&lt;/p&gt;

&lt;h2&gt;
  
  
  What can go wrong
&lt;/h2&gt;

&lt;p&gt;&lt;strong&gt;The IP rule is there, but everyone still gets in.&lt;/strong&gt; An older &lt;code&gt;ALLOW IN Anywhere&lt;/code&gt; rule sits in the list. Run &lt;code&gt;sudo ufw status numbered&lt;/code&gt; and delete it (Step 5).&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;You're locked out, including from your own IP.&lt;/strong&gt; A &lt;code&gt;DENY&lt;/code&gt; rule sits above your &lt;code&gt;ALLOW&lt;/code&gt;. Rules run top to bottom. Use the provider's web console to log in, then &lt;code&gt;sudo ufw delete deny 22/tcp&lt;/code&gt; and add it again below your allow rule.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;It worked yesterday and times out today.&lt;/strong&gt; Your home IP changed. Most home connections get a new address now and then. Log in through the web console, add the new IP, and remove the old one. If it changes often, connect through a VPN with a fixed address, and allow that.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;You get blocked after a few quick connections.&lt;/strong&gt; That's &lt;code&gt;ufw limit&lt;/code&gt;. It blocks an address that opens 6 or more connections within 30 seconds, which scripts, &lt;code&gt;scp&lt;/code&gt; loops and Ansible runs can easily do. Use &lt;code&gt;allow&lt;/code&gt; for your own IP and keep &lt;code&gt;limit&lt;/code&gt; for anything wider.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;A Docker container's port is still reachable from anywhere.&lt;/strong&gt; Ports published with &lt;code&gt;docker run -p&lt;/code&gt; are handled by Docker's own firewall rules, which ufw doesn't see. Publish internal ports on &lt;code&gt;127.0.0.1&lt;/code&gt; only (&lt;code&gt;-p 127.0.0.1:5432:5432&lt;/code&gt;), or don't publish them at all.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Blocked from your own machine even though the rule looks right.&lt;/strong&gt; Your computer may be connecting over IPv6 while you allowed its IPv4 address. Check &lt;code&gt;$SSH_CLIENT&lt;/code&gt; again and allow the address it shows, or connect with &lt;code&gt;ssh -4&lt;/code&gt;.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;The firewall turned itself off.&lt;/strong&gt; That's the Step 3 timer doing its job. Fix the rule, then start the timer again before you retry.&lt;/p&gt;

&lt;h2&gt;
  
  
  FAQ
&lt;/h2&gt;

&lt;h3&gt;
  
  
  How do I allow SSH from only one IP address with ufw?
&lt;/h3&gt;

&lt;p&gt;Run &lt;code&gt;sudo ufw allow from YOUR_IP to any port 22 proto tcp&lt;/code&gt;, make sure the default incoming policy is deny, and delete any rule that allows port 22 from anywhere. Then test from a new terminal.&lt;/p&gt;

&lt;h3&gt;
  
  
  Do I need to restart anything after changing ufw rules?
&lt;/h3&gt;

&lt;p&gt;No. ufw applies rules the moment you add them. Only changes to &lt;code&gt;sshd_config&lt;/code&gt; need &lt;code&gt;sudo systemctl reload ssh&lt;/code&gt;.&lt;/p&gt;

&lt;h3&gt;
  
  
  What if my home IP changes?
&lt;/h3&gt;

&lt;p&gt;Use the provider's web console to add the new address. To avoid it, allow a VPN or office address that doesn't change, rather than a home connection.&lt;/p&gt;

&lt;h3&gt;
  
  
  Can I allow a range of IPs?
&lt;/h3&gt;

&lt;p&gt;Yes: &lt;code&gt;sudo ufw allow from 203.0.113.0/24 to any port 22 proto tcp&lt;/code&gt; allows 256 addresses. Allow the smallest range that covers you.&lt;/p&gt;

&lt;h3&gt;
  
  
  Should I use ufw or my cloud provider's firewall?
&lt;/h3&gt;

&lt;p&gt;Use both if you can. The provider's firewall stops traffic before it reaches the server, and it still works if a package update or a script changes ufw. ufw on the server is the backup layer.&lt;/p&gt;

&lt;h3&gt;
  
  
  Is changing the SSH port enough instead?
&lt;/h3&gt;

&lt;p&gt;No. A different port cuts log noise from bots, but anyone who scans the server finds it. An IP allowlist actually blocks them.&lt;/p&gt;

&lt;h3&gt;
  
  
  How do I get back in if I lock myself out?
&lt;/h3&gt;

&lt;p&gt;Wait for the Step 3 timer if you set one. Otherwise open the provider's web or VNC console, log in, and run &lt;code&gt;sudo ufw disable&lt;/code&gt;. Fix the rules, then enable it again.&lt;/p&gt;

&lt;h2&gt;
  
  
  Do it on a Hubfly space Box
&lt;/h2&gt;

&lt;p&gt;A &lt;a href="https://www.hubfly.space/docs/box/?ref=allow-ssh-from-specific-ip-only" rel="noopener noreferrer"&gt;Hubfly space Box&lt;/a&gt; is a Linux VM with root access, so the ufw steps above work inside it. It also has its own &lt;a href="https://www.hubfly.space/docs/box/firewall/?ref=allow-ssh-from-specific-ip-only" rel="noopener noreferrer"&gt;Box firewall&lt;/a&gt; in front of the VM: a Box-level policy that each network interface inherits or overrides, with ordered rules that set the action, protocol, selectors and ports. A new Box allows only the inbound traffic you list, so check that list as well as ufw.&lt;/p&gt;

&lt;p&gt;SSH reaches a Box through a TCP port mapping, and the public port is assigned for you. Connect with &lt;code&gt;ssh -p &amp;lt;assigned-port&amp;gt; deploy@&amp;lt;box-address&amp;gt;&lt;/code&gt;; inside the VM, the ufw rule still uses port 22.&lt;/p&gt;

&lt;p&gt;If SSH stops answering, the Box dashboard gives you a short-lived &lt;a href="https://www.hubfly.space/docs/box/access-and-monitoring/?ref=allow-ssh-from-specific-ip-only" rel="noopener noreferrer"&gt;browser console&lt;/a&gt;, which is the recovery path from "What can go wrong".&lt;/p&gt;

&lt;p&gt;Before you rely on rules inside the VM, run Step 1 on the Box. If &lt;code&gt;$SSH_CLIENT&lt;/code&gt; doesn't show your own address, filter by IP in the Box firewall instead.&lt;/p&gt;

&lt;h2&gt;
  
  
  Go further on Hubfly space
&lt;/h2&gt;

&lt;ul&gt;
&lt;li&gt;Not sure you need a full VM? &lt;a href="https://blog.hubfly.space/container-vs-vm-side-project?utm_source=devto&amp;amp;utm_medium=crosspost&amp;amp;utm_campaign=allow-ssh-from-specific-ip-only" rel="noopener noreferrer"&gt;Container vs VM for a side project&lt;/a&gt; compares both with real prices.&lt;/li&gt;
&lt;li&gt;Keep admin tools off the open internet entirely: &lt;a href="https://blog.hubfly.space/deploy-mcp-server-https-access-key?utm_source=devto&amp;amp;utm_medium=crosspost&amp;amp;utm_campaign=allow-ssh-from-specific-ip-only" rel="noopener noreferrer"&gt;Deploy your own MCP server with HTTPS and an access key&lt;/a&gt; shows access keys on a public endpoint.&lt;/li&gt;
&lt;li&gt;Running a web app rather than a VM? The &lt;a href="https://www.hubfly.space/docs/firewall/?ref=allow-ssh-from-specific-ip-only" rel="noopener noreferrer"&gt;Hubfly space firewall&lt;/a&gt; puts IP and CIDR rules, user-agent blocking and rate limits in front of each domain, with no server setup.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;&lt;a href="https://www.hubfly.space/?ref=allow-ssh-from-specific-ip-only" rel="noopener noreferrer"&gt;&lt;strong&gt;Try it on Hubfly space →&lt;/strong&gt;&lt;/a&gt;: create a Box, lock SSH to your IP, and keep the console as your way back in.&lt;/p&gt;




&lt;p&gt;&lt;em&gt;By Octave · drafted with AI, reviewed by Octave · Last updated 6 November 2026&lt;/em&gt;&lt;/p&gt;

&lt;p&gt;&lt;em&gt;Originally published on the &lt;a href="https://blog.hubfly.space/allow-ssh-from-specific-ip-only?utm_source=devto&amp;amp;utm_medium=crosspost&amp;amp;utm_campaign=allow-ssh-from-specific-ip-only" rel="noopener noreferrer"&gt;Hubfly space blog&lt;/a&gt;.&lt;/em&gt;&lt;/p&gt;

</description>
      <category>linux</category>
      <category>security</category>
      <category>ssh</category>
      <category>devops</category>
    </item>
    <item>
      <title>Cheapest way to host a Node.js app in 2026 (real prices)</title>
      <dc:creator>octave Nkurunziza</dc:creator>
      <pubDate>Sat, 07 Nov 2026 12:09:06 +0000</pubDate>
      <link>https://dev.to/octave_nkurunziza_afb0512/cheapest-way-to-host-a-nodejs-app-in-2026-real-prices-50lc</link>
      <guid>https://dev.to/octave_nkurunziza_afb0512/cheapest-way-to-host-a-nodejs-app-in-2026-real-prices-50lc</guid>
      <description>&lt;p&gt;You built a Node.js API or a small Express app and you want it online without paying $20 a month for something that serves a few hundred requests a day. This guide shows the cheapest way to host a Node app in 2026 for each situation: free for a hobby project, about $2 a month for a small always-on API, and about $4 a month with a real Postgres database. It also shows the one memory setting that keeps a Node app stable on a small 256 MB or 512 MB plan, because the cheapest plan is useless if the app keeps dying.&lt;/p&gt;

&lt;p&gt;&lt;a href="https://hubfly.space/?ref=cheapest-way-to-host-node-app" rel="noopener noreferrer"&gt;&lt;strong&gt;Try it on Hubfly space →&lt;/strong&gt;&lt;/a&gt;: run a small Node API always-on for about $2.23 a month, or free on the shared tier (after a one-time $5 prepaid deposit).&lt;/p&gt;

&lt;h2&gt;
  
  
  The cheapest way to host a Node app: short answer
&lt;/h2&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Your situation&lt;/th&gt;
&lt;th&gt;Cheapest sensible option&lt;/th&gt;
&lt;th&gt;Monthly cost&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;Hobby project, OK if the first request is slow&lt;/td&gt;
&lt;td&gt;A free tier that sleeps (Hubfly space shared tier after a $5 prepaid deposit, Render Free)&lt;/td&gt;
&lt;td&gt;$0&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Small API that must answer instantly&lt;/td&gt;
&lt;td&gt;An always-on 512 MB container&lt;/td&gt;
&lt;td&gt;$2.23–$7&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;API plus a Postgres database&lt;/td&gt;
&lt;td&gt;512 MB container + the smallest managed Postgres&lt;/td&gt;
&lt;td&gt;about $4.15 and up&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;You enjoy running Linux servers&lt;/td&gt;
&lt;td&gt;A $4–$6 VPS&lt;/td&gt;
&lt;td&gt;$4–$6 plus your time&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Static frontend only (React, Vite build)&lt;/td&gt;
&lt;td&gt;A static host's free plan&lt;/td&gt;
&lt;td&gt;$0&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;p&gt;The rest of this post shows where those numbers come from, what each free tier really gives you, and how to fit a Node app into the smallest plan without crashes.&lt;/p&gt;

&lt;h2&gt;
  
  
  How much memory a Node.js app needs
&lt;/h2&gt;

&lt;p&gt;Most "cheapest Node hosting" lists skip this question, yet it decides your price. Every platform below charges by RAM size, so the smallest size your app fits in is the cheapest plan you can use.&lt;/p&gt;

&lt;p&gt;A minimal Express 5 API on &lt;strong&gt;Node.js 22&lt;/strong&gt; (one JSON route and a health route, &lt;code&gt;NODE_ENV=production&lt;/code&gt;) used:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;About 55 MB&lt;/strong&gt; of RAM (resident memory) when idle.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;About 130 MB at peak&lt;/strong&gt; under 50 concurrent connections, serving roughly 12,700 requests a second on 2 CPU cores.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;So a typical small API fits in &lt;strong&gt;256 MB&lt;/strong&gt;, and &lt;strong&gt;512 MB&lt;/strong&gt; leaves room for a database driver, an ORM and a few dependencies. You only need 1 GB or more for heavy work: image processing with &lt;code&gt;sharp&lt;/code&gt;, PDF generation, large in-memory caches, or server-side rendering of big pages.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Why it matters:&lt;/strong&gt; jumping from 512 MB to 1 GB roughly doubles the price on every usage-priced platform. Measure first, then pick the size.&lt;/p&gt;

&lt;p&gt;To check your own app, run it locally and read its memory:&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_ENV&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;production node server.js &amp;amp;
ps &lt;span class="nt"&gt;-o&lt;/span&gt; &lt;span class="nv"&gt;rss&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nt"&gt;-p&lt;/span&gt; &lt;span class="nv"&gt;$!&lt;/span&gt; | &lt;span class="nb"&gt;awk&lt;/span&gt; &lt;span class="s1"&gt;'{print $1/1024 " MB"}'&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Then put it under load (for example with &lt;code&gt;npx autocannon -c 50 -d 20 http://localhost:3000/your-route&lt;/code&gt;) and check again. Size your plan at about twice the peak you see.&lt;/p&gt;

&lt;h2&gt;
  
  
  The 256 MB trap: set Node's heap limit yourself
&lt;/h2&gt;

&lt;p&gt;Here's the gotcha that makes small plans look unreliable. On a container with a &lt;strong&gt;256 MB&lt;/strong&gt; memory limit, Node.js 22 sets its JavaScript heap limit to about &lt;strong&gt;259 MB&lt;/strong&gt;: more than the whole container. Node notices the container limit, but the heap it picks is still too large for it.&lt;/p&gt;

&lt;p&gt;What happens when memory grows (a leak, a big upload, a huge JSON response):&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;Without a heap limit:&lt;/strong&gt; the container hits 256 MB first and the kernel kills it with &lt;strong&gt;exit code 137&lt;/strong&gt;. The logs are &lt;strong&gt;empty&lt;/strong&gt;: no error, no stack trace. You just see a restart.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;With &lt;code&gt;--max-old-space-size=192&lt;/code&gt;:&lt;/strong&gt; Node stops at 192 MB of heap and prints &lt;code&gt;FATAL ERROR: Reached heap limit Allocation failed - JavaScript heap out of memory&lt;/code&gt; in your logs, so you know exactly what happened.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;On a 512 MB limit, Node 22 picks a heap of about 259 MB, and on 1 GB about 524 MB, so larger plans are safe by default. On the smallest plans, set the limit yourself with an environment variable. Leave about a quarter of the RAM for everything that isn't heap (buffers, native modules, the Node runtime itself):&lt;/p&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Container RAM&lt;/th&gt;
&lt;th&gt;Set NODE_OPTIONS to&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;256 MB&lt;/td&gt;
&lt;td&gt;&lt;code&gt;--max-old-space-size=192&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;512 MB&lt;/td&gt;
&lt;td&gt;&lt;code&gt;--max-old-space-size=384&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;1 GB&lt;/td&gt;
&lt;td&gt;&lt;code&gt;--max-old-space-size=768&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;p&gt;&lt;code&gt;NODE_OPTIONS&lt;/code&gt; works on every platform in this post because it's read by Node itself, so you don't need to change your start command. If your app already restarts with exit code 137, the fix list under "What can go wrong" below covers the usual causes.&lt;/p&gt;

&lt;h2&gt;
  
  
  Node.js hosting prices compared (November 2026)
&lt;/h2&gt;

&lt;p&gt;Prices below are for the smallest plan that can run a long-lived Node server (Express, Fastify, NestJS, a WebSocket server), read from each official pricing page on 6 November 2026.&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;Free option for a Node server&lt;/th&gt;
&lt;th&gt;Smallest always-on plan&lt;/th&gt;
&lt;th&gt;Notes&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;&lt;strong&gt;Hubfly space&lt;/strong&gt;&lt;/td&gt;
&lt;td&gt;Shared tier: 0.3 vCPU, 256 MB, sleeps when idle, 360 active hours a month free&lt;/td&gt;
&lt;td&gt;
&lt;a href="https://www.hubfly.space/pricing?ref=cheapest-way-to-host-node-app" rel="noopener noreferrer"&gt;&lt;strong&gt;$2.23&lt;/strong&gt;&lt;/a&gt;: 0.5 vCPU, 512 MB, 4 GB disk&lt;/td&gt;
&lt;td&gt;Usage-priced (per vCPU-hour and GB-hour); managed Postgres from $1.92&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;strong&gt;Render&lt;/strong&gt;&lt;/td&gt;
&lt;td&gt;
&lt;a href="https://render.com/pricing" rel="noopener noreferrer"&gt;Free&lt;/a&gt;: 512 MB, spins down after 15 min without traffic, about 1 min to wake, 750 h per workspace&lt;/td&gt;
&lt;td&gt;
&lt;a href="https://render.com/pricing" rel="noopener noreferrer"&gt;$7&lt;/a&gt;: 512 MB, "less than 1 CPU"&lt;/td&gt;
&lt;td&gt;Free instances have no persistent disk&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;strong&gt;Railway&lt;/strong&gt;&lt;/td&gt;
&lt;td&gt;
&lt;a href="https://railway.com/pricing" rel="noopener noreferrer"&gt;30-day trial&lt;/a&gt; with $5 credit, then $1 a month&lt;/td&gt;
&lt;td&gt;
&lt;a href="https://docs.railway.com/pricing/plans" rel="noopener noreferrer"&gt;Hobby $5 minimum&lt;/a&gt;, which includes $5 of usage&lt;/td&gt;
&lt;td&gt;Usage at $10 per GB of RAM and $20 per vCPU a month&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;strong&gt;Fly.io&lt;/strong&gt;&lt;/td&gt;
&lt;td&gt;
&lt;a href="https://fly.io/pricing" rel="noopener noreferrer"&gt;$1 free to start&lt;/a&gt;, then pay as you go&lt;/td&gt;
&lt;td&gt;
&lt;a href="https://fly.io/pricing" rel="noopener noreferrer"&gt;$2.19&lt;/a&gt;: shared-cpu-1x, 256 MB; 512 MB about $3.69&lt;/td&gt;
&lt;td&gt;Extra RAM $6 per GB a month; North America prices&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;strong&gt;Heroku&lt;/strong&gt;&lt;/td&gt;
&lt;td&gt;None&lt;/td&gt;
&lt;td&gt;
&lt;a href="https://www.heroku.com/pricing/" rel="noopener noreferrer"&gt;Basic $7&lt;/a&gt;: 0.5 GB&lt;/td&gt;
&lt;td&gt;Eco $5 sleeps after 30 min of inactivity&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;strong&gt;DigitalOcean App Platform&lt;/strong&gt;&lt;/td&gt;
&lt;td&gt;
&lt;a href="https://www.digitalocean.com/pricing/app-platform" rel="noopener noreferrer"&gt;Static sites only&lt;/a&gt; (3 apps)&lt;/td&gt;
&lt;td&gt;
&lt;a href="https://www.digitalocean.com/pricing/app-platform" rel="noopener noreferrer"&gt;$5&lt;/a&gt;: 1 vCPU, 512 MiB&lt;/td&gt;
&lt;td&gt;50 GiB transfer included&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;strong&gt;DigitalOcean Droplet (VPS)&lt;/strong&gt;&lt;/td&gt;
&lt;td&gt;None&lt;/td&gt;
&lt;td&gt;
&lt;a href="https://www.digitalocean.com/pricing/droplets" rel="noopener noreferrer"&gt;$4&lt;/a&gt;: 1 vCPU, 512 MiB, 10 GiB SSD&lt;/td&gt;
&lt;td&gt;You manage the OS, updates, TLS and restarts&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;strong&gt;Vercel&lt;/strong&gt;&lt;/td&gt;
&lt;td&gt;
&lt;a href="https://vercel.com/pricing" rel="noopener noreferrer"&gt;Hobby&lt;/a&gt;: free, personal non-commercial use only&lt;/td&gt;
&lt;td&gt;Pro $20&lt;/td&gt;
&lt;td&gt;Runs Node as serverless functions, not a long-lived server&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;p&gt;The Fly.io 512 MB figure is the 256 MB preset ($2.19) plus 256 MB of extra RAM at $6 per GB ($1.50).&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Where others win, honestly:&lt;/strong&gt;&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;DigitalOcean's $4 Droplet&lt;/strong&gt; gives you 1 shared vCPU, 512 MiB and 500 GiB of transfer. If you're comfortable patching Ubuntu, setting up Nginx, Certbot and a process manager, it's hard to beat on raw resources. Your time is the hidden cost.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Render Free&lt;/strong&gt; gives 750 hours a month, more than Hubfly space's 360 free hours, if a one-minute wake-up is fine for you.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Vercel Hobby&lt;/strong&gt; is the easiest free home for a Next.js frontend that you don't sell. It's the wrong tool for a long-running Express server, WebSockets or background jobs.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Railway's Hobby plan&lt;/strong&gt; suits people who run several tiny services: the $5 covers all of them as long as total usage stays under $5.&lt;/li&gt;
&lt;/ul&gt;

&lt;h2&gt;
  
  
  The total bill: Node API plus Postgres
&lt;/h2&gt;

&lt;p&gt;Almost every real app needs a database, and that's where cheap hosting stops being cheap. Here is one always-on Node API (512 MB) plus the smallest managed Postgres each platform sells:&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;Node API&lt;/th&gt;
&lt;th&gt;Smallest managed Postgres&lt;/th&gt;
&lt;th&gt;Total per month&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;&lt;strong&gt;Hubfly space&lt;/strong&gt;&lt;/td&gt;
&lt;td&gt;$2.23 (0.5 vCPU, 512 MB)&lt;/td&gt;
&lt;td&gt;$1.92 (Nano: 0.25 vCPU, 512 MiB, 1 GiB)&lt;/td&gt;
&lt;td&gt;&lt;strong&gt;$4.15&lt;/strong&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;strong&gt;Render&lt;/strong&gt;&lt;/td&gt;
&lt;td&gt;$7&lt;/td&gt;
&lt;td&gt;$6 (256 MB RAM, storage $0.30 per GB)&lt;/td&gt;
&lt;td&gt;&lt;strong&gt;$13 plus storage&lt;/strong&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;strong&gt;Heroku&lt;/strong&gt;&lt;/td&gt;
&lt;td&gt;$7 (Basic)&lt;/td&gt;
&lt;td&gt;$5 (Essential-0, 1 GB)&lt;/td&gt;
&lt;td&gt;&lt;strong&gt;$12&lt;/strong&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;strong&gt;Railway&lt;/strong&gt;&lt;/td&gt;
&lt;td&gt;Hobby $5 minimum covers small usage&lt;/td&gt;
&lt;td&gt;Runs inside the same usage&lt;/td&gt;
&lt;td&gt;&lt;strong&gt;$5 or more&lt;/strong&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;p&gt;Render and Heroku database prices come from the &lt;a href="https://blog.hubfly.space/cheapest-database-small-app-2026?utm_source=devto&amp;amp;utm_medium=crosspost&amp;amp;utm_campaign=cheapest-way-to-host-node-app" rel="noopener noreferrer"&gt;cheapest database for a small app&lt;/a&gt; comparison, which also covers Neon, Supabase and Turso free tiers. If you'd rather keep the database on SQLite, put the file on a persistent volume: a 1 GB Standard volume on Hubfly space costs about $0.01 a month. Never keep SQLite on a container's normal disk, because that disk is wiped on every redeploy.&lt;/p&gt;

&lt;h3&gt;
  
  
  How the Hubfly space numbers add up
&lt;/h3&gt;

&lt;p&gt;Hubfly space charges $0.004 per vCPU-hour, $0.002 per GB-hour of RAM and $0.00001536 per GB-hour of Standard storage, over a 730-hour month:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;CPU: 0.5 vCPU × $0.004 × 730 h = &lt;strong&gt;$1.46&lt;/strong&gt;
&lt;/li&gt;
&lt;li&gt;RAM: 0.5 GB × $0.002 × 730 h = &lt;strong&gt;$0.73&lt;/strong&gt;
&lt;/li&gt;
&lt;li&gt;Disk: 4 GB × $0.00001536 × 730 h = &lt;strong&gt;$0.04&lt;/strong&gt;
&lt;/li&gt;
&lt;li&gt;Total: &lt;strong&gt;$2.23 a month&lt;/strong&gt;, running 24/7.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;The shared tier (0.3 vCPU, 256 MB) is free for up to 360 active hours a month and sleeps when idle, so a hobby API that is idle most of the day can stay within the free hours. Creating resources needs a one-time &lt;strong&gt;deposit of $5 or more&lt;/strong&gt;; it's prepaid credit that your usage draws from, not a fee.&lt;/p&gt;

&lt;h2&gt;
  
  
  Deploy a Node app on about $2 a month
&lt;/h2&gt;

&lt;p&gt;This works on any container platform. The example uses Hubfly space.&lt;/p&gt;

&lt;h3&gt;
  
  
  1. Make the app container-friendly
&lt;/h3&gt;

&lt;p&gt;Two lines matter most. Read the port from the &lt;code&gt;PORT&lt;/code&gt; variable, and listen on &lt;code&gt;0.0.0.0&lt;/code&gt;, not &lt;code&gt;localhost&lt;/code&gt;:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight javascript"&gt;&lt;code&gt;&lt;span class="c1"&gt;// server.js&lt;/span&gt;
&lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;express&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nf"&gt;require&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;express&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;

&lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;app&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nf"&gt;express&lt;/span&gt;&lt;span class="p"&gt;();&lt;/span&gt;
&lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;port&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nx"&gt;process&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;env&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;PORT&lt;/span&gt; &lt;span class="o"&gt;||&lt;/span&gt; &lt;span class="mi"&gt;3000&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

&lt;span class="nx"&gt;app&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;get&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;/health&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;req&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nx"&gt;res&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="o"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="nx"&gt;res&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;send&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;ok&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;));&lt;/span&gt;
&lt;span class="nx"&gt;app&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;get&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;/api/products&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;req&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nx"&gt;res&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="o"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="nx"&gt;res&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;json&lt;/span&gt;&lt;span class="p"&gt;([{&lt;/span&gt; &lt;span class="na"&gt;id&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="mi"&gt;1&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="na"&gt;name&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;Mug&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="na"&gt;price&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="mi"&gt;12&lt;/span&gt; &lt;span class="p"&gt;}]));&lt;/span&gt;

&lt;span class="nx"&gt;app&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;listen&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;port&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;0.0.0.0&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="p"&gt;()&lt;/span&gt; &lt;span class="o"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="nx"&gt;console&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;log&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s2"&gt;`shop-api listening on &lt;/span&gt;&lt;span class="p"&gt;${&lt;/span&gt;&lt;span class="nx"&gt;port&lt;/span&gt;&lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="s2"&gt;`&lt;/span&gt;&lt;span class="p"&gt;));&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;&lt;strong&gt;Why &lt;code&gt;0.0.0.0&lt;/code&gt;:&lt;/strong&gt; an app bound to &lt;code&gt;127.0.0.1&lt;/code&gt; only answers from inside its own container, so the platform's proxy gets a 502. The &lt;a href="https://blog.hubfly.space/docker-502-bad-gateway-bind-0-0-0-0?utm_source=devto&amp;amp;utm_medium=crosspost&amp;amp;utm_campaign=cheapest-way-to-host-node-app" rel="noopener noreferrer"&gt;502 Bad Gateway fix&lt;/a&gt; explains it in detail.&lt;/p&gt;

&lt;p&gt;In &lt;code&gt;package.json&lt;/code&gt;, make sure &lt;code&gt;start&lt;/code&gt; runs plain Node, not &lt;code&gt;nodemon&lt;/code&gt;, and list only what the app needs at runtime in &lt;code&gt;dependencies&lt;/code&gt;:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight json"&gt;&lt;code&gt;&lt;span class="p"&gt;{&lt;/span&gt;&lt;span class="w"&gt;
  &lt;/span&gt;&lt;span class="nl"&gt;"name"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="s2"&gt;"shop-api"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;&lt;span class="w"&gt;
  &lt;/span&gt;&lt;span class="nl"&gt;"scripts"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="p"&gt;{&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nl"&gt;"start"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="s2"&gt;"node server.js"&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="p"&gt;},&lt;/span&gt;&lt;span class="w"&gt;
  &lt;/span&gt;&lt;span class="nl"&gt;"dependencies"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="p"&gt;{&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nl"&gt;"express"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="s2"&gt;"^5.1.0"&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="w"&gt;
&lt;/span&gt;&lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="w"&gt;
&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;h3&gt;
  
  
  2. Create the container
&lt;/h3&gt;

&lt;ol&gt;
&lt;li&gt;In the &lt;a href="https://dashboard.hubfly.space/?ref=cheapest-way-to-host-node-app" rel="noopener noreferrer"&gt;Hubfly space dashboard&lt;/a&gt;, create a &lt;strong&gt;Hubfly space Cell&lt;/strong&gt; project and pick the region closest to your users.&lt;/li&gt;
&lt;li&gt;Click &lt;strong&gt;Create Container&lt;/strong&gt; and choose your Git repository (GitHub, GitLab, Bitbucket, Gitea or Forgejo) as the source. Hubfly space detects a Node app from its package files, so no Dockerfile is needed.&lt;/li&gt;
&lt;li&gt;Pick the tier: &lt;strong&gt;Shared&lt;/strong&gt; for a free hobby app that may sleep, or &lt;strong&gt;Dedicated&lt;/strong&gt; at &lt;strong&gt;0.5 vCPU / 512 MB&lt;/strong&gt; for an always-on API. Turn &lt;strong&gt;Auto Sleep off&lt;/strong&gt; if the first request must be fast; the cost panel then shows &lt;strong&gt;$2.23/mo&lt;/strong&gt;.&lt;/li&gt;
&lt;li&gt;Under environment variables, add &lt;code&gt;NODE_ENV=production&lt;/code&gt; and the heap limit from the table above, for example &lt;code&gt;NODE_OPTIONS=--max-old-space-size=384&lt;/code&gt; for 512 MB.&lt;/li&gt;
&lt;li&gt;Deploy, then open &lt;strong&gt;Network → Add Domain → Auto Endpoint&lt;/strong&gt; to get an HTTPS address for port 3000.&lt;/li&gt;
&lt;/ol&gt;

&lt;h3&gt;
  
  
  3. Add a database only when you need it
&lt;/h3&gt;

&lt;p&gt;Create a &lt;strong&gt;Managed service → PostgreSQL&lt;/strong&gt; instance at the Nano size (from $1.92 a month) and paste its connection string into a &lt;code&gt;DATABASE_URL&lt;/code&gt; variable. Public access is on by default, so restrict it to the addresses that need it before you store real data. The &lt;a href="https://blog.hubfly.space/managed-postgresql-database-2-dollars-a-month?utm_source=devto&amp;amp;utm_medium=crosspost&amp;amp;utm_campaign=cheapest-way-to-host-node-app" rel="noopener noreferrer"&gt;$2 managed PostgreSQL guide&lt;/a&gt; covers the connection settings and access rules.&lt;/p&gt;

&lt;h3&gt;
  
  
  4. Put a ceiling on the bill
&lt;/h3&gt;

&lt;p&gt;Set a &lt;strong&gt;monthly budget cap&lt;/strong&gt; on the project. You get emails at 80% and 90%, and the dashboard says the project's running workloads stop at 100% instead of running up a surprise bill. For a $2 app, a $5 cap is plenty.&lt;/p&gt;

&lt;h2&gt;
  
  
  Cheap options that cost you later
&lt;/h2&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;Shared web hosting (cPanel plans at $2–$3):&lt;/strong&gt; some support Node through a "Node.js app" button, but often with old Node versions, no WebSockets and process limits that kill long-running servers. Fine for a static site, risky for an API.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Serverless for an Express app:&lt;/strong&gt; you can wrap Express in a function, but every cold start reloads the app, WebSockets don't work, and background timers die between requests.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Free tiers for anything with users:&lt;/strong&gt; a sleeping app makes the first visitor wait (about a minute on Render Free), and cron jobs or queue workers inside it simply don't run while it sleeps.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;PM2 cluster mode on a tiny plan:&lt;/strong&gt; on 0.5 vCPU, four workers just fight over the same half core and multiply memory use by four. In a container, run one Node process and let the platform restart it.&lt;/li&gt;
&lt;/ul&gt;

&lt;h2&gt;
  
  
  What can go wrong
&lt;/h2&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;The app restarts with exit code 137 and no logs.&lt;/strong&gt; It ran out of container memory. Set &lt;code&gt;NODE_OPTIONS=--max-old-space-size=…&lt;/code&gt; from the table above, then look for the leak or move up one size.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;&lt;code&gt;502 Bad Gateway&lt;/code&gt; right after deploy.&lt;/strong&gt; The app listens on &lt;code&gt;localhost&lt;/code&gt; or on a different port than the one you exposed. Listen on &lt;code&gt;0.0.0.0&lt;/code&gt; and &lt;code&gt;process.env.PORT&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;&lt;code&gt;JavaScript heap out of memory&lt;/code&gt; in the logs.&lt;/strong&gt; Good news: the limit works and you can see the problem. Find what grows (often an unbounded cache or loading a whole file into memory), or raise the plan and the limit together.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;The first request takes seconds, then it's fast.&lt;/strong&gt; The app was asleep. Use an always-on plan (Auto Sleep off) if that's a problem for your users.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Uploaded files or SQLite data vanish after a redeploy.&lt;/strong&gt; The container disk is temporary. Store files in object storage and databases on a volume or a managed database.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;The build fails at the install step.&lt;/strong&gt; &lt;code&gt;package-lock.json&lt;/code&gt; is often missing or out of sync with &lt;code&gt;package.json&lt;/code&gt;. Run &lt;code&gt;npm install&lt;/code&gt; locally, commit the lock file and redeploy.&lt;/li&gt;
&lt;/ul&gt;

&lt;h2&gt;
  
  
  FAQ
&lt;/h2&gt;

&lt;h3&gt;
  
  
  Can I host a Node.js app for free?
&lt;/h3&gt;

&lt;p&gt;Yes, if it can sleep. Hubfly space's shared tier (256 MB, 360 active hours a month) and Render Free (512 MB, 750 hours, about a minute to wake) both run a real Node server for $0 (Hubfly space asks for a one-time $5 deposit of prepaid credit before you create resources). Railway and Fly.io only give starter credit, and Heroku has no free plan.&lt;/p&gt;

&lt;h3&gt;
  
  
  What is the cheapest way to host a Node app that never sleeps?
&lt;/h3&gt;

&lt;p&gt;An always-on 512 MB container: $2.23 a month on Hubfly space, about $3.69 on Fly.io, $5 on DigitalOcean App Platform, or $7 on Render and Heroku. A $4 VPS is cheaper than most, but you run the server yourself.&lt;/p&gt;

&lt;h3&gt;
  
  
  Is Vercel free for a Node.js backend?
&lt;/h3&gt;

&lt;p&gt;Only for personal, non-commercial projects, and only as serverless functions. A long-running Express server, WebSockets or background workers need a container or a VPS.&lt;/p&gt;

&lt;h3&gt;
  
  
  How much RAM does a Node.js app need?
&lt;/h3&gt;

&lt;p&gt;A small Express API idles around 55 MB and peaks around 130 MB under 50 concurrent connections, so 256 MB works and 512 MB is comfortable. Image processing, server-side rendering or big caches need 1 GB or more.&lt;/p&gt;

&lt;h3&gt;
  
  
  Is a VPS cheaper than a PaaS for Node?
&lt;/h3&gt;

&lt;p&gt;On paper, sometimes: $4 for 512 MiB on DigitalOcean. But you also handle OS updates, firewall rules, TLS certificates, restarts and backups. For one small app, a $2–$5 container usually costs less once your time counts.&lt;/p&gt;

&lt;h3&gt;
  
  
  Do I need PM2 to host a Node app?
&lt;/h3&gt;

&lt;p&gt;On a VPS, yes, or a systemd service, so the app restarts after a crash or reboot. In a container platform, no: the platform restarts the container, and one Node process per container is the right setup.&lt;/p&gt;

&lt;h3&gt;
  
  
  Why does my Node app keep restarting on a small plan?
&lt;/h3&gt;

&lt;p&gt;Usually memory. On a 256 MB container, Node 22's default heap limit is bigger than the container, so the kernel kills the app with exit code 137 before Node can log anything. Set &lt;code&gt;NODE_OPTIONS=--max-old-space-size=192&lt;/code&gt;.&lt;/p&gt;

&lt;h3&gt;
  
  
  What's the cheapest way to host Node.js with a database?
&lt;/h3&gt;

&lt;p&gt;A 512 MB container plus the smallest managed Postgres: about $4.15 a month on Hubfly space, $12 on Heroku and $13 plus storage on Render. Or keep SQLite on a persistent volume for about a cent a month extra.&lt;/p&gt;

&lt;h2&gt;
  
  
  Go further on Hubfly space
&lt;/h2&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;Deploy on every push:&lt;/strong&gt; connect GitHub Actions so each merge ships automatically. See &lt;a href="https://blog.hubfly.space/deploy-on-push-github-actions-webhook?utm_source=devto&amp;amp;utm_medium=crosspost&amp;amp;utm_campaign=cheapest-way-to-host-node-app" rel="noopener noreferrer"&gt;deploy on push with GitHub Actions&lt;/a&gt; and the &lt;a href="https://www.hubfly.space/docs/deployment-pipelines/?ref=cheapest-way-to-host-node-app" rel="noopener noreferrer"&gt;deployment pipelines docs&lt;/a&gt;.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Add a managed database:&lt;/strong&gt; Postgres or SQLite (libSQL) from $1.92 a month, MySQL from $3.82. Start with the &lt;a href="https://www.hubfly.space/docs/databases/?ref=cheapest-way-to-host-node-app" rel="noopener noreferrer"&gt;Managed Databases docs&lt;/a&gt;.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Compare pricing models:&lt;/strong&gt; if your traffic is spiky, the &lt;a href="https://blog.hubfly.space/fixed-vs-pay-as-you-go-hosting-break-even?utm_source=devto&amp;amp;utm_medium=crosspost&amp;amp;utm_campaign=cheapest-way-to-host-node-app" rel="noopener noreferrer"&gt;fixed vs pay-as-you-go break-even guide&lt;/a&gt; shows when each one wins.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;&lt;a href="https://hubfly.space/?ref=cheapest-way-to-host-node-app" rel="noopener noreferrer"&gt;&lt;strong&gt;Try it on Hubfly space →&lt;/strong&gt;&lt;/a&gt;: put your Node app online for free on the shared tier (after a one-time $5 prepaid deposit), or always-on for $2.23 a month.&lt;/p&gt;




&lt;p&gt;&lt;em&gt;By Octave · drafted with AI, reviewed by Octave · Last updated 6 November 2026 · Applies to Node.js 22 LTS and Express 5&lt;/em&gt;&lt;/p&gt;

&lt;p&gt;&lt;em&gt;Originally published on the &lt;a href="https://blog.hubfly.space/cheapest-way-to-host-node-app?utm_source=devto&amp;amp;utm_medium=crosspost&amp;amp;utm_campaign=cheapest-way-to-host-node-app" rel="noopener noreferrer"&gt;Hubfly space blog&lt;/a&gt;.&lt;/em&gt;&lt;/p&gt;

</description>
      <category>node</category>
      <category>hosting</category>
      <category>docker</category>
      <category>webdev</category>
    </item>
    <item>
      <title>Migrate from Heroku without losing jobs: a step-by-step plan</title>
      <dc:creator>octave Nkurunziza</dc:creator>
      <pubDate>Wed, 04 Nov 2026 14:53:23 +0000</pubDate>
      <link>https://dev.to/octave_nkurunziza_afb0512/migrate-from-heroku-without-losing-jobs-a-step-by-step-plan-3epf</link>
      <guid>https://dev.to/octave_nkurunziza_afb0512/migrate-from-heroku-without-losing-jobs-a-step-by-step-plan-3epf</guid>
      <description>&lt;blockquote&gt;
&lt;p&gt;&lt;strong&gt;TL;DR&lt;/strong&gt;&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;What you get:&lt;/strong&gt; your Heroku app (web, worker, release phase, Postgres, Redis) running on Hubfly space, with a cutover plan that keeps downtime to the length of one database restore.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Who it's for:&lt;/strong&gt; teams on Heroku Basic or Eco dynos with Heroku Postgres Essential and Key-Value Store.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Time needed:&lt;/strong&gt; about an hour for the dry run, then a short maintenance window.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Cost:&lt;/strong&gt; the example app below drops from $22 a month on Heroku to about $8.34 on Hubfly space.&lt;/li&gt;
&lt;/ul&gt;
&lt;/blockquote&gt;

&lt;p&gt;Your app has run on Heroku for years. It works. But the bill keeps growing, and since February &lt;a href="https://www.heroku.com/blog/an-update-on-heroku/" rel="noopener noreferrer"&gt;Heroku is in a "sustaining engineering model"&lt;/a&gt;: it stays supported, with the focus on stability rather than new features. That's a fine reason to stay put, and an equally fine reason to plan your exit before you're forced to.&lt;/p&gt;

&lt;p&gt;This guide moves a typical Heroku app, one with a &lt;code&gt;Procfile&lt;/code&gt;, a worker, a &lt;code&gt;release&lt;/code&gt; command, Postgres and Redis, to Hubfly space. You'll turn the Procfile into a Compose file, copy your config vars, move the database with a real backup, and switch DNS with a rollback plan. Every step says why it matters, so you can adapt it to your own app.&lt;/p&gt;

&lt;p&gt;&lt;a href="https://hubfly.space" rel="noopener noreferrer"&gt;&lt;strong&gt;Try it on Hubfly space&lt;/strong&gt;&lt;/a&gt;: the free tier gives you 360 compute hours a month on the Shared tier with no card. The example in this guide runs on Dedicated containers and a managed database, about $8.34 a month.&lt;/p&gt;

&lt;h3&gt;
  
  
  Should you move at all?
&lt;/h3&gt;

&lt;p&gt;Be honest about this first. Heroku still does some things better than Hubfly space today:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;Scheduled backups and continuous protection.&lt;/strong&gt; On Heroku, one command (&lt;code&gt;heroku pg:backups:schedule DATABASE_URL --at '02:00 UTC' --app your-app&lt;/code&gt;) gives you &lt;a href="https://devcenter.heroku.com/articles/heroku-postgres-backups" rel="noopener noreferrer"&gt;daily backups&lt;/a&gt; kept for 7 days on Essential plans, and Standard plans and up add Continuous Protection. Hubfly space Managed Databases have no automatic backups or point-in-time restore yet (the dashboard says "Coming soon"), so you must schedule your own dumps.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;A built-in scheduler.&lt;/strong&gt; Heroku Scheduler runs one-off jobs on a timer. Hubfly space doesn't document a built-in scheduler, so you'll run a small clock process instead (shown below).&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Native Procfile and buildpacks.&lt;/strong&gt; Heroku reads your Procfile directly. On Hubfly space, you describe processes in a Compose file. It's a one-time translation, but it is work.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Review apps, pipelines and the add-on marketplace.&lt;/strong&gt; If your team leans on these, count them as real migration cost.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;Move if the bill matters, if you want everything (apps, databases, storage, mail) in one place, or if you'd rather own a standard Compose file than a platform-specific setup. If you want to compare more destinations first, read &lt;a href="https://blog.hubfly.space/heroku-alternatives-2026-prices?utm_source=devto&amp;amp;utm_medium=referral&amp;amp;utm_campaign=migrate-from-heroku" rel="noopener noreferrer"&gt;Best Heroku alternatives in 2026&lt;/a&gt;.&lt;/p&gt;

&lt;h3&gt;
  
  
  What it costs: the same app on both platforms
&lt;/h3&gt;

&lt;p&gt;The example app is a small online shop API: one web process, one background worker, a release command that runs migrations, Postgres and Redis.&lt;/p&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Part&lt;/th&gt;
&lt;th&gt;Heroku (prices from &lt;a href="https://www.heroku.com/pricing" rel="noopener noreferrer"&gt;heroku.com/pricing&lt;/a&gt;, 4 Nov 2026)&lt;/th&gt;
&lt;th&gt;Hubfly space&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;Web&lt;/td&gt;
&lt;td&gt;Basic dyno, 0.5 GB: $7&lt;/td&gt;
&lt;td&gt;Dedicated 0.5 vCPU, 512 MB, 4 GB disk: $2.23&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Worker&lt;/td&gt;
&lt;td&gt;Basic dyno, 0.5 GB: $7&lt;/td&gt;
&lt;td&gt;Dedicated 0.5 vCPU, 512 MB, 4 GB disk: $2.23&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Release command&lt;/td&gt;
&lt;td&gt;Runs in a one-off dyno during each release&lt;/td&gt;
&lt;td&gt;Compose job that runs for a few seconds per deploy (the Stack Composer estimate counts it as up to $2.23)&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Postgres&lt;/td&gt;
&lt;td&gt;Essential-0 (1 GB disk): $5&lt;/td&gt;
&lt;td&gt;Managed PostgreSQL Nano (0.25 vCPU, 512 MiB, 10 GiB): $2.02&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Redis&lt;/td&gt;
&lt;td&gt;Key-Value Store Mini (25 MB): $3&lt;/td&gt;
&lt;td&gt;Redis container, 0.5 vCPU, 256 MB, 1 GB disk, 1 GB volume: $1.85&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;strong&gt;Total per month&lt;/strong&gt;&lt;/td&gt;
&lt;td&gt;&lt;strong&gt;$22&lt;/strong&gt;&lt;/td&gt;
&lt;td&gt;&lt;strong&gt;about $8.34&lt;/strong&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;p&gt;The Hubfly space numbers come from the &lt;a href="https://www.hubfly.space/pricing" rel="noopener noreferrer"&gt;published rates&lt;/a&gt;: $0.004 per vCPU-hour, $0.002 per GB-hour of RAM, $0.00001536 per GB-hour of storage, 730 hours a month.&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;Web or worker: 0.5 × 0.004 × 730 = $1.46 CPU, plus 0.5 × 0.002 × 730 = $0.73 RAM, plus 4 × 0.00001536 × 730 = $0.04 disk. Total &lt;strong&gt;$2.23&lt;/strong&gt;.&lt;/li&gt;
&lt;li&gt;Redis: $1.46 CPU, plus 0.25 × 0.002 × 730 = $0.37 RAM, plus 1 × 0.00001536 × 730 = $0.01 disk, plus a 1 GB Balanced volume at 1 × 0.00002304 × 730 = $0.02. Total &lt;strong&gt;$1.85&lt;/strong&gt;.&lt;/li&gt;
&lt;li&gt;Postgres Nano: 0.25 × 0.004 × 730 = $0.73 CPU, plus 0.5 × 0.002 × 730 = $0.73 RAM, plus a 30% management fee on that compute ($0.44), plus 11 GiB of storage (10 GiB data and a 1 GiB system disk) at $0.12. Total &lt;strong&gt;$2.02&lt;/strong&gt;.&lt;/li&gt;
&lt;li&gt;Sum: 2.2349 + 2.2349 + 1.8530 + 2.0213 = &lt;strong&gt;$8.34&lt;/strong&gt;.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;The Stack Composer shows &lt;strong&gt;$8.54&lt;/strong&gt; for the four Compose services before the Redis volume is added. It counts the release job as if it ran all month, and it leaves out the managed database, which is priced on its own create page. In practice the job runs for a few seconds per deploy.&lt;/p&gt;

&lt;p&gt;Two fair notes on this table. Heroku's Basic dyno includes a share of CPU described as "1x-4x" compute, so the CPU isn't a like-for-like match. And Heroku's Key-Value Store Mini is a managed service, while the Hubfly space Redis is a container you run yourself (with a lot more memory). Jobs queued in Heroku's Key-Value Store are not copied over, so you drain the queue during the cutover (Step 6).&lt;/p&gt;

&lt;p&gt;&lt;a href="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2F00lghl6epe4anm2nwbig.png" class="article-body-image-wrapper"&gt;&lt;img src="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2F00lghl6epe4anm2nwbig.png" alt="The Stack Composer with the four services from the Procfile and a monthly estimate" width="800" height="355"&gt;&lt;/a&gt;&lt;/p&gt;

&lt;h3&gt;
  
  
  Step 1: Take inventory of your Heroku app
&lt;/h3&gt;

&lt;p&gt;You can't move what you haven't listed. Run these three commands and save the output:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;heroku ps &lt;span class="nt"&gt;--app&lt;/span&gt; your-app            &lt;span class="c"&gt;# your dyno formation: which processes run, and how many&lt;/span&gt;
heroku addons &lt;span class="nt"&gt;--app&lt;/span&gt; your-app        &lt;span class="c"&gt;# Postgres, Key-Value Store, Scheduler, logging, email...&lt;/span&gt;
heroku config &lt;span class="nt"&gt;--shell&lt;/span&gt; &lt;span class="nt"&gt;--app&lt;/span&gt; your-app &lt;span class="o"&gt;&amp;gt;&lt;/span&gt; heroku.env   &lt;span class="c"&gt;# every config var, in KEY=value form&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;&lt;code&gt;heroku.env&lt;/code&gt; now holds every secret your app uses. Treat it like a password file: don't commit it, and delete it when you're done.&lt;/p&gt;

&lt;p&gt;Then open your &lt;code&gt;Procfile&lt;/code&gt;. The example app has three lines:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;release: node migrate.js
web: node web.js
worker: node worker.js
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;h3&gt;
  
  
  Step 2: Turn the Procfile into a Compose file
&lt;/h3&gt;

&lt;p&gt;Each Procfile line becomes one Compose service. This is the core of the migration, so here's the mapping:&lt;/p&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Heroku&lt;/th&gt;
&lt;th&gt;Hubfly space Compose&lt;/th&gt;
&lt;th&gt;Why&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;
&lt;code&gt;web:&lt;/code&gt; process&lt;/td&gt;
&lt;td&gt;a service with &lt;code&gt;ports&lt;/code&gt; and &lt;code&gt;PORT&lt;/code&gt; set&lt;/td&gt;
&lt;td&gt;Heroku injects &lt;code&gt;$PORT&lt;/code&gt;; on Hubfly space you set it yourself&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;
&lt;code&gt;worker:&lt;/code&gt; process&lt;/td&gt;
&lt;td&gt;a service with no ports&lt;/td&gt;
&lt;td&gt;Workers only talk to Redis and Postgres&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;
&lt;code&gt;release:&lt;/code&gt; process&lt;/td&gt;
&lt;td&gt;a service with &lt;code&gt;restart: "no"&lt;/code&gt;
&lt;/td&gt;
&lt;td&gt;It runs once and exits; Hubfly space imports it as a &lt;strong&gt;Job&lt;/strong&gt;
&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Release must succeed before web boots&lt;/td&gt;
&lt;td&gt;&lt;code&gt;depends_on: release: condition: service_completed_successfully&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;A failed migration stops the deploy, just like Heroku's release phase&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Key-Value Store add-on&lt;/td&gt;
&lt;td&gt;a &lt;code&gt;redis:7-alpine&lt;/code&gt; service&lt;/td&gt;
&lt;td&gt;Reached on the private network by name&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Heroku Postgres add-on&lt;/td&gt;
&lt;td&gt;Hubfly space Managed PostgreSQL&lt;/td&gt;
&lt;td&gt;Connection string goes into &lt;code&gt;DATABASE_URL&lt;/code&gt;
&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;
&lt;code&gt;clock:&lt;/code&gt; process or Heroku Scheduler&lt;/td&gt;
&lt;td&gt;a &lt;code&gt;clock&lt;/code&gt; service running a scheduler library&lt;/td&gt;
&lt;td&gt;Hubfly space doesn't document a built-in scheduler&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;p&gt;Here's the full file for the example app. Replace &lt;code&gt;ghcr.io/your-org/shop-api:1.0.0&lt;/code&gt; with your own image, and the &lt;code&gt;DATABASE_URL&lt;/code&gt; values with the ones from Step 4:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight yaml"&gt;&lt;code&gt;&lt;span class="na"&gt;services&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt;
  &lt;span class="na"&gt;cache&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt;
    &lt;span class="na"&gt;image&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="s"&gt;redis:7-alpine&lt;/span&gt;
    &lt;span class="na"&gt;volumes&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt;
      &lt;span class="pi"&gt;-&lt;/span&gt; &lt;span class="s"&gt;redisdata:/data&lt;/span&gt;
    &lt;span class="na"&gt;healthcheck&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt;
      &lt;span class="na"&gt;test&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="pi"&gt;[&lt;/span&gt;&lt;span class="s2"&gt;"&lt;/span&gt;&lt;span class="s"&gt;CMD"&lt;/span&gt;&lt;span class="pi"&gt;,&lt;/span&gt; &lt;span class="s2"&gt;"&lt;/span&gt;&lt;span class="s"&gt;redis-cli"&lt;/span&gt;&lt;span class="pi"&gt;,&lt;/span&gt; &lt;span class="s2"&gt;"&lt;/span&gt;&lt;span class="s"&gt;ping"&lt;/span&gt;&lt;span class="pi"&gt;]&lt;/span&gt;
      &lt;span class="na"&gt;interval&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="s"&gt;5s&lt;/span&gt;
      &lt;span class="na"&gt;timeout&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="s"&gt;3s&lt;/span&gt;
      &lt;span class="na"&gt;retries&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="m"&gt;10&lt;/span&gt;
  &lt;span class="na"&gt;release&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt;
    &lt;span class="na"&gt;image&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="s"&gt;ghcr.io/your-org/shop-api:1.0.0&lt;/span&gt;
    &lt;span class="na"&gt;command&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="pi"&gt;[&lt;/span&gt;&lt;span class="s2"&gt;"&lt;/span&gt;&lt;span class="s"&gt;node"&lt;/span&gt;&lt;span class="pi"&gt;,&lt;/span&gt; &lt;span class="s2"&gt;"&lt;/span&gt;&lt;span class="s"&gt;migrate.js"&lt;/span&gt;&lt;span class="pi"&gt;]&lt;/span&gt;
    &lt;span class="na"&gt;restart&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"&lt;/span&gt;&lt;span class="s"&gt;no"&lt;/span&gt;
    &lt;span class="na"&gt;environment&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt;
      &lt;span class="na"&gt;DATABASE_URL&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"&lt;/span&gt;&lt;span class="s"&gt;postgres://admin:your-admin-password@your-db-host:your-port/app?sslmode=require"&lt;/span&gt;
  &lt;span class="na"&gt;web&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt;
    &lt;span class="na"&gt;image&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="s"&gt;ghcr.io/your-org/shop-api:1.0.0&lt;/span&gt;
    &lt;span class="na"&gt;command&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="pi"&gt;[&lt;/span&gt;&lt;span class="s2"&gt;"&lt;/span&gt;&lt;span class="s"&gt;node"&lt;/span&gt;&lt;span class="pi"&gt;,&lt;/span&gt; &lt;span class="s2"&gt;"&lt;/span&gt;&lt;span class="s"&gt;web.js"&lt;/span&gt;&lt;span class="pi"&gt;]&lt;/span&gt;
    &lt;span class="na"&gt;environment&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt;
      &lt;span class="na"&gt;PORT&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"&lt;/span&gt;&lt;span class="s"&gt;3000"&lt;/span&gt;
      &lt;span class="na"&gt;DATABASE_URL&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"&lt;/span&gt;&lt;span class="s"&gt;postgres://app_user:your-password@your-db-host:your-port/app?sslmode=require"&lt;/span&gt;
      &lt;span class="na"&gt;REDIS_URL&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"&lt;/span&gt;&lt;span class="s"&gt;redis://{{service:cache.host}}:6379"&lt;/span&gt;
    &lt;span class="na"&gt;ports&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt;
      &lt;span class="pi"&gt;-&lt;/span&gt; &lt;span class="s2"&gt;"&lt;/span&gt;&lt;span class="s"&gt;3000:3000"&lt;/span&gt;
    &lt;span class="na"&gt;depends_on&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt;
      &lt;span class="na"&gt;release&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt;
        &lt;span class="na"&gt;condition&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="s"&gt;service_completed_successfully&lt;/span&gt;
      &lt;span class="na"&gt;cache&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt;
        &lt;span class="na"&gt;condition&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="s"&gt;service_healthy&lt;/span&gt;
  &lt;span class="na"&gt;worker&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt;
    &lt;span class="na"&gt;image&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="s"&gt;ghcr.io/your-org/shop-api:1.0.0&lt;/span&gt;
    &lt;span class="na"&gt;command&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="pi"&gt;[&lt;/span&gt;&lt;span class="s2"&gt;"&lt;/span&gt;&lt;span class="s"&gt;node"&lt;/span&gt;&lt;span class="pi"&gt;,&lt;/span&gt; &lt;span class="s2"&gt;"&lt;/span&gt;&lt;span class="s"&gt;worker.js"&lt;/span&gt;&lt;span class="pi"&gt;]&lt;/span&gt;
    &lt;span class="na"&gt;environment&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt;
      &lt;span class="na"&gt;DATABASE_URL&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"&lt;/span&gt;&lt;span class="s"&gt;postgres://app_user:your-password@your-db-host:your-port/app?sslmode=require"&lt;/span&gt;
      &lt;span class="na"&gt;REDIS_URL&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"&lt;/span&gt;&lt;span class="s"&gt;redis://{{service:cache.host}}:6379"&lt;/span&gt;
    &lt;span class="na"&gt;depends_on&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt;
      &lt;span class="na"&gt;release&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt;
        &lt;span class="na"&gt;condition&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="s"&gt;service_completed_successfully&lt;/span&gt;
      &lt;span class="na"&gt;cache&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt;
        &lt;span class="na"&gt;condition&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="s"&gt;service_healthy&lt;/span&gt;
&lt;span class="na"&gt;volumes&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt;
  &lt;span class="na"&gt;redisdata&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The &lt;code&gt;redisdata&lt;/code&gt; volume keeps queued jobs when Redis restarts or redeploys; everything outside a volume is wiped on redeploy. &lt;code&gt;{{service:cache.host}}&lt;/code&gt; is a Hubfly space reference: it resolves to the Redis container's private hostname, so you never hard-code an address.&lt;/p&gt;

&lt;p&gt;Your web process must listen on &lt;code&gt;0.0.0.0&lt;/code&gt;, not &lt;code&gt;127.0.0.1&lt;/code&gt;. Heroku hides this detail; on any container platform an app bound to localhost returns a &lt;a href="https://blog.hubfly.space/docker-502-bad-gateway-bind-0-0-0-0?utm_source=devto&amp;amp;utm_medium=referral&amp;amp;utm_campaign=migrate-from-heroku" rel="noopener noreferrer"&gt;502 Bad Gateway&lt;/a&gt;.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Need a Dockerfile?&lt;/strong&gt; Heroku built your app with a buildpack. Hubfly space can &lt;a href="https://www.hubfly.space/docs/builds/" rel="noopener noreferrer"&gt;auto-detect common stacks from Git&lt;/a&gt;, or you can add a small Dockerfile so the build is the same everywhere. For a Node app:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight docker"&gt;&lt;code&gt;&lt;span class="k"&gt;FROM&lt;/span&gt;&lt;span class="s"&gt; node:22-alpine&lt;/span&gt;
&lt;span class="k"&gt;WORKDIR&lt;/span&gt;&lt;span class="s"&gt; /app&lt;/span&gt;
&lt;span class="k"&gt;COPY&lt;/span&gt;&lt;span class="s"&gt; package.json package-lock.json ./&lt;/span&gt;
&lt;span class="k"&gt;RUN &lt;/span&gt;npm ci &lt;span class="nt"&gt;--omit&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;dev
&lt;span class="k"&gt;COPY&lt;/span&gt;&lt;span class="s"&gt; . .&lt;/span&gt;
&lt;span class="k"&gt;USER&lt;/span&gt;&lt;span class="s"&gt; node&lt;/span&gt;
&lt;span class="k"&gt;CMD&lt;/span&gt;&lt;span class="s"&gt; ["node", "web.js"]&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The &lt;code&gt;command&lt;/code&gt; lines in the Compose file override &lt;code&gt;CMD&lt;/code&gt;, so one image serves web, worker and release, exactly like one Heroku slug did.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Make your release command safe to run twice.&lt;/strong&gt; Heroku already asks for this in its &lt;a href="https://devcenter.heroku.com/articles/release-phase" rel="noopener noreferrer"&gt;release phase guide&lt;/a&gt;: migrations should check whether they've already run and take an advisory lock. The same command now runs on every Hubfly space deploy, so the same rule applies:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight javascript"&gt;&lt;code&gt;&lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="nx"&gt;client&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;query&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;SELECT pg_advisory_lock(42)&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
&lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="nx"&gt;client&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;query&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;CREATE TABLE IF NOT EXISTS orders (id serial PRIMARY KEY, item text NOT NULL, done boolean DEFAULT false)&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
&lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="nx"&gt;client&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;query&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;SELECT pg_advisory_unlock(42)&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;&lt;strong&gt;Replacing Heroku Scheduler.&lt;/strong&gt; Add a &lt;code&gt;clock&lt;/code&gt; service that runs a scheduler library (node-cron, APScheduler, sidekiq-cron) and enqueues jobs for the worker. Heroku documents the same pattern as &lt;a href="https://devcenter.heroku.com/articles/scheduled-jobs-custom-clock-processes" rel="noopener noreferrer"&gt;custom clock processes&lt;/a&gt;. A 0.5 vCPU / 256 MB clock container with a 1 GB disk costs about $1.84 a month.&lt;/p&gt;

&lt;h3&gt;
  
  
  Step 3: Import the stack
&lt;/h3&gt;

&lt;ol&gt;
&lt;li&gt;In the &lt;a href="https://dashboard.hubfly.space" rel="noopener noreferrer"&gt;dashboard&lt;/a&gt;, click &lt;strong&gt;Create Project&lt;/strong&gt;, choose &lt;strong&gt;Cell&lt;/strong&gt; and a region. Under &lt;strong&gt;Advanced Options&lt;/strong&gt;, set a monthly budget cap with headroom (for example $50 for this stack). The dashboard says that reaching the cap stops the project's containers and blocks deploys, and they don't restart on their own, so don't set it too tight.&lt;/li&gt;
&lt;li&gt;Open the project, click &lt;strong&gt;Create → Compose Stack&lt;/strong&gt;, open the &lt;strong&gt;YAML&lt;/strong&gt; tab, paste your file and click &lt;strong&gt;Import YAML&lt;/strong&gt;.&lt;/li&gt;
&lt;li&gt;Check each service. &lt;code&gt;release&lt;/code&gt; shows &lt;strong&gt;Kind: Job&lt;/strong&gt;, &lt;strong&gt;Restart Policy: Never&lt;/strong&gt; and &lt;strong&gt;Deploy Stage 2&lt;/strong&gt;, after &lt;code&gt;cache&lt;/code&gt; and before &lt;code&gt;web&lt;/code&gt; and &lt;code&gt;worker&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;Imported services start on the Shared tier, which sleeps when idle and only runs within your free hours. A worker that sleeps stops processing jobs, so switch all four services, &lt;code&gt;release&lt;/code&gt; included, to &lt;strong&gt;Dedicated&lt;/strong&gt; under &lt;strong&gt;Resources&lt;/strong&gt;, with Auto Sleep off for &lt;code&gt;web&lt;/code&gt;, &lt;code&gt;worker&lt;/code&gt; and &lt;code&gt;cache&lt;/code&gt;. If the release job can't start, the whole stack rolls back.&lt;/li&gt;
&lt;/ol&gt;

&lt;p&gt;&lt;a href="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Ftjfx6zgf3dwfy30xtpr6.png" class="article-body-image-wrapper"&gt;&lt;img src="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Ftjfx6zgf3dwfy30xtpr6.png" alt="Service settings for the release job: Kind Job, Restart Policy Never, Deploy Stage 2" width="800" height="355"&gt;&lt;/a&gt;&lt;/p&gt;

&lt;p&gt;Don't deploy yet. The database comes first.&lt;/p&gt;

&lt;h3&gt;
  
  
  Step 4: Create the database and copy your config vars
&lt;/h3&gt;

&lt;ol&gt;
&lt;li&gt;
&lt;strong&gt;Create the database.&lt;/strong&gt; &lt;strong&gt;Create Project → Managed service → PostgreSQL&lt;/strong&gt;, size &lt;strong&gt;Nano&lt;/strong&gt;. Provisioning takes a minute or two. The host ends in &lt;code&gt;.db.hubfly.app&lt;/code&gt; and the port is the one the &lt;strong&gt;Connect&lt;/strong&gt; page shows (not 5432).&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Restrict access.&lt;/strong&gt; In &lt;strong&gt;Network&lt;/strong&gt;, add your own IP to the allowlist. An empty allowlist means anyone with the password can try to connect.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Create an app user.&lt;/strong&gt; In &lt;strong&gt;Users&lt;/strong&gt;, create a user with the &lt;strong&gt;Read &amp;amp; write&lt;/strong&gt; preset and store the password; it's shown once.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Copy the config vars.&lt;/strong&gt; Open &lt;code&gt;heroku.env&lt;/code&gt;. Drop the lines Heroku add-ons manage (&lt;code&gt;DATABASE_URL&lt;/code&gt;, &lt;code&gt;REDIS_URL&lt;/code&gt; and any &lt;code&gt;HEROKU_POSTGRESQL_*&lt;/code&gt;), because they now point at new services. Add each remaining variable to your services in the Compose file, or in each container's &lt;strong&gt;Configuration → Environment Variables&lt;/strong&gt; after deploy, with &lt;strong&gt;Secret&lt;/strong&gt; on for anything sensitive.&lt;/li&gt;
&lt;/ol&gt;

&lt;p&gt;Put variables on the containers, not only at project level: containers created from a Compose stack don't pick up project-level variables.&lt;/p&gt;

&lt;p&gt;Use the &lt;strong&gt;admin&lt;/strong&gt; connection string from the &lt;strong&gt;Connect&lt;/strong&gt; page for the restore in Steps 5 and 6, because restoring creates schemas and tables. Your app then connects as the Read &amp;amp; write user. Give the &lt;code&gt;release&lt;/code&gt; service the admin &lt;code&gt;DATABASE_URL&lt;/code&gt; too: the restored tables belong to admin, so a migration that alters them as another user fails with &lt;code&gt;must be owner&lt;/code&gt;.&lt;/p&gt;

&lt;h3&gt;
  
  
  Step 5: Rehearse the database move while Heroku stays live
&lt;/h3&gt;

&lt;p&gt;A rehearsal tells you exactly how long your maintenance window must be. Heroku backups use &lt;code&gt;pg_dump&lt;/code&gt;'s custom format, so standard tools restore them:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;heroku pg:backups:capture &lt;span class="nt"&gt;--app&lt;/span&gt; your-app
heroku pg:backups:download &lt;span class="nt"&gt;--app&lt;/span&gt; your-app      &lt;span class="c"&gt;# saves latest.dump&lt;/span&gt;

&lt;span class="nb"&gt;time &lt;/span&gt;pg_restore &lt;span class="nt"&gt;--verbose&lt;/span&gt; &lt;span class="nt"&gt;--no-owner&lt;/span&gt; &lt;span class="nt"&gt;--no-acl&lt;/span&gt; &lt;span class="nt"&gt;--exit-on-error&lt;/span&gt; &lt;span class="se"&gt;\&lt;/span&gt;
  &lt;span class="nt"&gt;-d&lt;/span&gt; &lt;span class="s2"&gt;"postgres://admin:your-admin-password@your-db-host:your-port/app?sslmode=require"&lt;/span&gt; &lt;span class="se"&gt;\&lt;/span&gt;
  latest.dump
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Use PostgreSQL 18 client tools (&lt;code&gt;pg_restore --version&lt;/code&gt;), because Hubfly space creates PostgreSQL 18 by default and older clients can refuse newer formats. &lt;code&gt;--no-owner --no-acl&lt;/code&gt; skips Heroku's role names, which don't exist on the new server.&lt;/p&gt;

&lt;p&gt;Then compare row counts on both sides for your busiest tables:&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;count&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="o"&gt;*&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="k"&gt;FROM&lt;/span&gt; &lt;span class="n"&gt;orders&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;On a local machine, a 100,000-row, 16 MB database dumps and restores in under a second each. Over the internet, download and upload time adds to that, so write down your own timing: that's your downtime.&lt;/p&gt;

&lt;p&gt;Now deploy the stack against this restored copy and load a few pages through an &lt;strong&gt;Auto Endpoint&lt;/strong&gt; (under the web container's &lt;strong&gt;Network&lt;/strong&gt; tab). Keep the rehearsal from touching the real world: leave &lt;code&gt;worker&lt;/code&gt; and &lt;code&gt;clock&lt;/code&gt; stopped, or swap payment, email and webhook keys for test keys. This shows your containers can reach the database and that the app works on the new platform before any user sees it.&lt;/p&gt;

&lt;p&gt;When you're done, stop the stack, drop and recreate the target database (or create a fresh one) so the real run starts clean, and delete &lt;code&gt;latest.dump&lt;/code&gt;.&lt;/p&gt;

&lt;h3&gt;
  
  
  Step 6: The cutover
&lt;/h3&gt;

&lt;ol&gt;
&lt;li&gt;
&lt;strong&gt;Lower your DNS TTL&lt;/strong&gt; to 60 seconds a day before, so the switch spreads fast.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Turn on maintenance mode:&lt;/strong&gt; note your formation from &lt;code&gt;heroku ps&lt;/code&gt;, then run &lt;code&gt;heroku maintenance:on --app your-app&lt;/code&gt;. Visitors see Heroku's maintenance page, and no new jobs are queued from web requests.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Drain the queue, then stop workers and the clock.&lt;/strong&gt; &lt;a href="https://devcenter.heroku.com/articles/maintenance-mode" rel="noopener noreferrer"&gt;Maintenance mode&lt;/a&gt; doesn't stop workers or scheduler jobs. Wait until your queue is empty, then run &lt;code&gt;heroku ps:scale worker=0 clock=0 --app your-app&lt;/code&gt; (list only the process types you have) and pause your Heroku Scheduler jobs.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Capture, download and restore&lt;/strong&gt; the final backup with the Step 5 commands.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Deploy the stack&lt;/strong&gt; in the Stack Composer. The release job migrates, then web and worker start.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Smoke test&lt;/strong&gt; through the Auto Endpoint: try the paths your users hit most.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Switch DNS.&lt;/strong&gt; Add your domain in the web container's &lt;strong&gt;Custom Domain&lt;/strong&gt; tab, complete the verification the dashboard shows, and point your DNS at the target it gives you (CNAME for &lt;code&gt;www&lt;/code&gt;, ALIAS or ANAME for the apex).&lt;/li&gt;
&lt;/ol&gt;

&lt;p&gt;&lt;strong&gt;Rollback plan:&lt;/strong&gt; if something breaks before DNS spreads, point DNS back to Heroku, run &lt;code&gt;heroku maintenance:off --app your-app&lt;/code&gt;, restore the formation you recorded in step 2 with &lt;code&gt;heroku ps:scale&lt;/code&gt;, and resume your Heroku Scheduler jobs. Writes made on Hubfly space after the switch won't be on Heroku, so decide within the first hour.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Keep Heroku for a week&lt;/strong&gt;, scaled down. Before destroying the app, make sure no DNS record still points at the Heroku app, then remove the domain (&lt;code&gt;heroku domains:remove www.your-domain.com --app your-app&lt;/code&gt;). Heroku &lt;a href="https://devcenter.heroku.com/articles/custom-domains" rel="noopener noreferrer"&gt;warns&lt;/a&gt; that a DNS record still pointing at a deleted app invites subdomain takeover.&lt;/p&gt;

&lt;h3&gt;
  
  
  What can go wrong
&lt;/h3&gt;

&lt;ol&gt;
&lt;li&gt;
&lt;strong&gt;Jobs vanish during the switch.&lt;/strong&gt; A Heroku worker left running keeps pulling jobs and writing results to the old database, so they never show up in the new one. Jobs still sitting in Heroku's queue are lost too. Fix: turn on maintenance mode, let the queue drain, then scale workers and clock to zero before the final backup, and only start the new worker after the restore.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;&lt;code&gt;pg_restore&lt;/code&gt; fails on &lt;code&gt;heroku_ext&lt;/code&gt;.&lt;/strong&gt; Heroku databases can have extensions in a &lt;code&gt;heroku_ext&lt;/code&gt; schema. Fix: connect as the admin user, run &lt;code&gt;CREATE SCHEMA heroku_ext;&lt;/code&gt; on the target, then restore again. This is &lt;a href="https://devcenter.heroku.com/articles/heroku-postgres-import-export" rel="noopener noreferrer"&gt;Heroku's own advice&lt;/a&gt; for restoring elsewhere.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;502 after deploy.&lt;/strong&gt; The app listens on &lt;code&gt;127.0.0.1&lt;/code&gt; or on a port other than &lt;code&gt;PORT&lt;/code&gt;. Fix: bind &lt;code&gt;0.0.0.0&lt;/code&gt; and make sure the endpoint port matches &lt;code&gt;PORT&lt;/code&gt; (3000 in the example).&lt;/li&gt;
&lt;/ol&gt;

&lt;h3&gt;
  
  
  Takeaway
&lt;/h3&gt;

&lt;p&gt;A Heroku app is three things: a Procfile, config vars and add-ons. The Procfile becomes a Compose file with a job for &lt;code&gt;release&lt;/code&gt;. Config vars move once by hand. Postgres moves with the same backup file Heroku already makes. Rehearse the restore, stop the workers before the final dump, and keep Heroku as your rollback for a week.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Next reads:&lt;/strong&gt; &lt;a href="https://blog.hubfly.space/migrate-from-render?utm_source=devto&amp;amp;utm_medium=referral&amp;amp;utm_campaign=migrate-from-heroku" rel="noopener noreferrer"&gt;How to migrate from Render to Hubfly space&lt;/a&gt; and &lt;a href="https://blog.hubfly.space/migrate-from-railway?utm_source=devto&amp;amp;utm_medium=referral&amp;amp;utm_campaign=migrate-from-heroku" rel="noopener noreferrer"&gt;How to move your app from Railway to Hubfly space&lt;/a&gt;.&lt;/p&gt;

&lt;h3&gt;
  
  
  Go further on Hubfly space
&lt;/h3&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;Back up your database every night&lt;/strong&gt;: until automatic backups arrive, add a small job that runs &lt;code&gt;pg_dump&lt;/code&gt; to &lt;a href="https://www.hubfly.space/docs/storage/" rel="noopener noreferrer"&gt;Hubfly space Storage&lt;/a&gt; (S3-compatible, about $0.011 per GB-month).&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Deploy on every push&lt;/strong&gt; with &lt;a href="https://blog.hubfly.space/deploy-on-push-github-actions-webhook?utm_source=devto&amp;amp;utm_medium=referral&amp;amp;utm_campaign=migrate-from-heroku" rel="noopener noreferrer"&gt;GitHub Actions and a deploy webhook&lt;/a&gt;, so you keep Heroku's &lt;code&gt;git push&lt;/code&gt; workflow.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Add health checks&lt;/strong&gt; so failing containers are caught early: &lt;a href="https://blog.hubfly.space/docker-health-checks-postgres-redis?utm_source=devto&amp;amp;utm_medium=referral&amp;amp;utm_campaign=migrate-from-heroku" rel="noopener noreferrer"&gt;Docker health checks that catch real problems&lt;/a&gt;.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;&lt;a href="https://hubfly.space" rel="noopener noreferrer"&gt;&lt;strong&gt;Start your migration on Hubfly space&lt;/strong&gt;&lt;/a&gt;: rehearse on a copy first, and switch only when the numbers check out.&lt;/p&gt;

</description>
      <category>heroku</category>
      <category>docker</category>
      <category>postgres</category>
      <category>devops</category>
    </item>
    <item>
      <title>Coolify vs Railway and Render: what self-hosting really costs</title>
      <dc:creator>octave Nkurunziza</dc:creator>
      <pubDate>Wed, 04 Nov 2026 14:52:46 +0000</pubDate>
      <link>https://dev.to/octave_nkurunziza_afb0512/coolify-vs-railway-and-render-what-self-hosting-really-costs-3l56</link>
      <guid>https://dev.to/octave_nkurunziza_afb0512/coolify-vs-railway-and-render-what-self-hosting-really-costs-3l56</guid>
      <description>&lt;blockquote&gt;
&lt;p&gt;&lt;strong&gt;TL;DR&lt;/strong&gt;&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;What you get:&lt;/strong&gt; a side-by-side monthly bill for one small web app plus Postgres on Coolify (self-hosted and Cloud), Railway, Render and Hubfly space, plus a worksheet for the hours self-hosting takes.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Who it's for:&lt;/strong&gt; developers and small teams deciding between "my own server with Coolify" and "a platform that runs it for me".&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Time to read:&lt;/strong&gt; 10 minutes. Prices checked on 4 November 2026.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Short answer:&lt;/strong&gt; for one or two small apps, a managed platform is usually cheaper &lt;em&gt;and&lt;/em&gt; less work. Coolify starts to win at roughly 5 to 12 small apps on one server, depending on whether they share a database and how much memory they need, if you're happy owning backups and updates.&lt;/li&gt;
&lt;/ul&gt;
&lt;/blockquote&gt;

&lt;p&gt;Your Railway or Render bill keeps creeping up, and Coolify looks like a free way out. You rent a server, run one install command, and get Git deploys, databases and HTTPS in a nice dashboard. No platform bill.&lt;/p&gt;

&lt;p&gt;But the server isn't free, the backups aren't automatic until you set them up, and nobody patches it for you. This guide puts real numbers on both sides, so you can pick the option that costs you less in money &lt;em&gt;and&lt;/em&gt; in evenings.&lt;/p&gt;

&lt;p&gt;&lt;a href="https://dashboard.hubfly.space" rel="noopener noreferrer"&gt;Try it on Hubfly space&lt;/a&gt;: the free tier gives you 360 hours a month, no card needed.&lt;/p&gt;

&lt;h2&gt;
  
  
  What Coolify is (and why people love it)
&lt;/h2&gt;

&lt;p&gt;&lt;a href="https://coolify.io/pricing" rel="noopener noreferrer"&gt;Coolify&lt;/a&gt; is an open-source, self-hostable platform. You connect your own servers and it handles Git deploys, Docker images, Compose stacks, one-click services and databases.&lt;/p&gt;

&lt;p&gt;It's a good piece of software, and it wins on several things:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;No platform fee if you self-host.&lt;/strong&gt; The self-hosted edition is "Free forever" with every feature, per &lt;a href="https://coolify.io/pricing" rel="noopener noreferrer"&gt;Coolify's pricing page&lt;/a&gt;.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Many apps on one bill.&lt;/strong&gt; You pay for the server, not per app. Ten tiny apps can share one box.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Real database backups.&lt;/strong&gt; Coolify can schedule backups for PostgreSQL, MySQL, MariaDB, MongoDB, ClickHouse and SQLite, and upload a copy to any S3-compatible storage (&lt;a href="https://coolify.io/docs/databases/backups" rel="noopener noreferrer"&gt;backups docs&lt;/a&gt;).&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Portability.&lt;/strong&gt; It runs on almost any Linux box: a VPS, a dedicated server, even a Raspberry Pi.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;No lock-in.&lt;/strong&gt; Your apps are plain Docker containers on a machine you control.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;If you already run Linux servers for a living, Coolify is a great tool. The question is what it costs everyone else.&lt;/p&gt;

&lt;h2&gt;
  
  
  The two ways to run Coolify
&lt;/h2&gt;

&lt;p&gt;&lt;strong&gt;Self-hosted.&lt;/strong&gt; You install Coolify on your own server. &lt;a href="https://coolify.io/docs/get-started/installation" rel="noopener noreferrer"&gt;The install guide&lt;/a&gt; asks for at least &lt;strong&gt;2 CPU cores, 2 GB RAM and 10 GB of disk&lt;/strong&gt;, on a supported Linux distribution, with SSH access and the right firewall ports open. Then you run one script.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Coolify Cloud.&lt;/strong&gt; The Coolify team runs the dashboard for you. It costs &lt;strong&gt;$5 a month for up to 2 connected servers, plus $3 a month for each extra server&lt;/strong&gt;, and you still bring and pay for your own servers (&lt;a href="https://coolify.io/pricing" rel="noopener noreferrer"&gt;pricing&lt;/a&gt;). The upside: the control plane's updates and backups are managed, and your server only needs room for your apps.&lt;/p&gt;

&lt;p&gt;Either way, the server running your apps is still yours to look after.&lt;/p&gt;

&lt;h2&gt;
  
  
  The reference app
&lt;/h2&gt;

&lt;p&gt;Whether you're weighing Coolify vs Railway or Render, every option below runs the same small setup:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;One web app&lt;/strong&gt;, always on, about 512 MB of memory.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;One small Postgres database.&lt;/strong&gt;&lt;/li&gt;
&lt;li&gt;Low traffic: a side project, an internal tool or an early-stage SaaS.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;Bandwidth is left out because the plans bundle it very differently. Check it separately if you serve a lot of files or video.&lt;/p&gt;

&lt;h2&gt;
  
  
  The monthly bill, side by side
&lt;/h2&gt;

&lt;p&gt;Prices from each vendor's official page on &lt;strong&gt;4 November 2026&lt;/strong&gt;, in US dollars, before tax.&lt;/p&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Option&lt;/th&gt;
&lt;th&gt;What you pay for&lt;/th&gt;
&lt;th&gt;Monthly cost&lt;/th&gt;
&lt;th&gt;Backups included in that price?&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;
&lt;strong&gt;Coolify self-hosted&lt;/strong&gt; on a &lt;a href="https://www.digitalocean.com/pricing/droplets" rel="noopener noreferrer"&gt;DigitalOcean Droplet&lt;/a&gt; (2 vCPU, 2 GiB, $18)&lt;/td&gt;
&lt;td&gt;Server + weekly server backups (20% of Droplet price)&lt;/td&gt;
&lt;td&gt;&lt;strong&gt;$21.60&lt;/strong&gt;&lt;/td&gt;
&lt;td&gt;Weekly server image. Database dumps to S3 are free to set up in Coolify, plus storage cost&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;
&lt;strong&gt;Coolify Cloud&lt;/strong&gt; + a &lt;a href="https://www.digitalocean.com/pricing/droplets" rel="noopener noreferrer"&gt;1 vCPU / 2 GiB Droplet&lt;/a&gt; ($12)&lt;/td&gt;
&lt;td&gt;
&lt;a href="https://coolify.io/pricing" rel="noopener noreferrer"&gt;$5 Coolify Cloud&lt;/a&gt; + server + weekly backups&lt;/td&gt;
&lt;td&gt;&lt;strong&gt;$19.40&lt;/strong&gt;&lt;/td&gt;
&lt;td&gt;Same as above; Coolify itself is backed up for you&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;
&lt;a href="https://railway.com/pricing" rel="noopener noreferrer"&gt;&lt;strong&gt;Railway&lt;/strong&gt;&lt;/a&gt; Hobby&lt;/td&gt;
&lt;td&gt;$5 plan that includes $5 of usage, then usage&lt;/td&gt;
&lt;td&gt;
&lt;strong&gt;about $10.81&lt;/strong&gt; (see math below)&lt;/td&gt;
&lt;td&gt;Built-in database and volume backups are listed on the &lt;a href="https://railway.com/pricing" rel="noopener noreferrer"&gt;pricing page&lt;/a&gt;; check which plans include them&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;a href="https://render.com/pricing" rel="noopener noreferrer"&gt;&lt;strong&gt;Render&lt;/strong&gt;&lt;/a&gt;&lt;/td&gt;
&lt;td&gt;$7 web service (512 MB) + $6 Postgres (256 MB)&lt;/td&gt;
&lt;td&gt;&lt;strong&gt;$13.00&lt;/strong&gt;&lt;/td&gt;
&lt;td&gt;Yes: logical backups on paid Postgres instances, plus point-in-time recovery (window depends on your workspace plan)&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;strong&gt;Hubfly space&lt;/strong&gt;&lt;/td&gt;
&lt;td&gt;Dedicated container (0.5 vCPU, 512 MB, always on) + Managed Postgres Nano&lt;/td&gt;
&lt;td&gt;&lt;strong&gt;$4.26&lt;/strong&gt;&lt;/td&gt;
&lt;td&gt;
&lt;strong&gt;No automatic database backups yet.&lt;/strong&gt; Use manual exports&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;p&gt;A few honest notes on that table:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;Railway bills measured usage, so a busier app costs more.&lt;/strong&gt; Hubfly space bills the CPU and memory you allocate per hour, so its bill changes only when you resize or add containers. Render, Droplets and Coolify Cloud are fixed monthly plans.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Render also offers up to $10K in migration credits&lt;/strong&gt; for teams moving production workloads (&lt;a href="https://render.com/pricing" rel="noopener noreferrer"&gt;pricing page&lt;/a&gt;). That can matter more than a few dollars a month.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Hubfly space's database has no automatic backups or point-in-time recovery today.&lt;/strong&gt; Its &lt;a href="https://www.hubfly.space/docs/databases/pricing-and-limits/" rel="noopener noreferrer"&gt;pricing docs&lt;/a&gt; say automatic backups are "coming soon" and point you to manual exports. On that one point, Coolify's scheduled S3 backups are ahead.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;&lt;a href="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2F3hg7qlzepuunb0zzdiye.png" class="article-body-image-wrapper"&gt;&lt;img src="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2F3hg7qlzepuunb0zzdiye.png" alt="The cost panel for a 1 vCPU, 1 GB always-on container: $4.42 a month" width="800" height="277"&gt;&lt;/a&gt;&lt;/p&gt;

&lt;p&gt;&lt;em&gt;The Create Container cost panel shows the monthly price before you deploy. Here: 1 vCPU and 1 GB, always on.&lt;/em&gt;&lt;/p&gt;

&lt;h2&gt;
  
  
  How the numbers are calculated
&lt;/h2&gt;

&lt;p&gt;You can redo every line yourself. Months are 730 hours.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Hubfly space&lt;/strong&gt; (rates from the &lt;a href="https://www.hubfly.space/pricing" rel="noopener noreferrer"&gt;pricing page&lt;/a&gt;: CPU $0.004 per vCPU-hour, RAM $0.002 per GB-hour, storage $0.00001536 per GB-hour):&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;Web container, 0.5 vCPU / 512 MB / 4 GB disk, always on:
0.5 × 0.004 × 730 = $1.46, plus 0.5 × 0.002 × 730 = $0.73, plus 4 × 0.00001536 × 730 = $0.04. &lt;strong&gt;Total $2.23.&lt;/strong&gt;
&lt;/li&gt;
&lt;li&gt;Managed Postgres Nano (0.25 vCPU, 512 MiB, 10 GiB), from the &lt;a href="https://www.hubfly.space/docs/databases/pricing-and-limits/" rel="noopener noreferrer"&gt;database pricing docs&lt;/a&gt;: compute $0.002 per hour + system disk $0.00001536 + 30% management fee $0.0006 + storage $0.0001536 = $0.00276896 per hour. &lt;strong&gt;About $2.02 a month.&lt;/strong&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Together: $4.26.&lt;/strong&gt; Want a full vCPU and 1 GB for the web app instead? That container is $4.42 (screenshot above), so the total is $6.44.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;&lt;strong&gt;Railway&lt;/strong&gt; (rates from the &lt;a href="https://railway.com/pricing" rel="noopener noreferrer"&gt;pricing page&lt;/a&gt;): $0.00000772 per vCPU-second ($20.29 per vCPU-month), $0.00000386 per GB-second ($10.14 per GB-month), volumes $0.00000006 per GB-second ($0.16 per GB-month). Railway bills what your app actually uses, so the bill depends on load. Assume:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;Web app averages 0.1 vCPU and 512 MB: 0.1 × 20.29 + 0.5 × 10.14 = $7.10.&lt;/li&gt;
&lt;li&gt;Postgres averages 0.05 vCPU, 256 MB and a 1 GB volume: 0.05 × 20.29 + 0.25 × 10.14 + 0.16 = $3.71.&lt;/li&gt;
&lt;li&gt;Usage $10.81. The $5 Hobby plan includes $5 of usage, so the &lt;strong&gt;bill is about $10.81&lt;/strong&gt;.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;&lt;strong&gt;Render:&lt;/strong&gt; $7 (web service, 512 MB) + $6 (smallest paid Postgres, 256 MB) = &lt;strong&gt;$13&lt;/strong&gt;, on the free Hobby workspace.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Coolify self-hosted:&lt;/strong&gt; the smallest &lt;a href="https://www.digitalocean.com/pricing/droplets" rel="noopener noreferrer"&gt;Droplet&lt;/a&gt; that meets Coolify's 2-core, 2 GB minimum is 2 vCPU / 2 GiB at $18. Weekly Droplet backups cost 20% of the Droplet price ($3.60). &lt;strong&gt;Total $21.60.&lt;/strong&gt; Daily backups are 30% ($5.40), for $23.40.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Coolify Cloud:&lt;/strong&gt; $5 + a 1 vCPU / 2 GiB Droplet at $12 + 20% weekly backups ($2.40) = &lt;strong&gt;$19.40&lt;/strong&gt;.&lt;/p&gt;

&lt;p&gt;Coolify's own docs often suggest Hetzner, which is usually cheaper than DigitalOcean. On 4 November 2026, though, &lt;a href="https://www.hetzner.com/cloud/regular-performance" rel="noopener noreferrer"&gt;Hetzner's Regular Performance page&lt;/a&gt; listed its plans as "currently unavailable", so it isn't in the table. If you can get a Hetzner server, redo the Coolify rows with its price.&lt;/p&gt;

&lt;h2&gt;
  
  
  The cost nobody puts in the table: your hours
&lt;/h2&gt;

&lt;p&gt;A platform bill is only half the price. With self-hosted Coolify you also own:&lt;/p&gt;

&lt;ol&gt;
&lt;li&gt;
&lt;strong&gt;The server.&lt;/strong&gt; OS updates, SSH keys, firewall rules, disk space. Docker images and old builds fill disks quietly.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Coolify itself.&lt;/strong&gt; You can turn on automatic updates, which install new releases on a schedule (daily at midnight by default, per the &lt;a href="https://coolify.io/docs/get-started/upgrade" rel="noopener noreferrer"&gt;update docs&lt;/a&gt;). The dashboard restarts briefly during an update, and the docs advise taking an instance backup and reading the release notes first.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Security.&lt;/strong&gt; Coolify's automated install needs root access to your server, so its bugs matter. Its GitHub repository lists &lt;a href="https://github.com/coollabsio/coolify/security/advisories" rel="noopener noreferrer"&gt;70 published security advisories&lt;/a&gt; as of 4 November 2026. Publishing them openly is a good sign, but someone on your team needs to read them and update promptly.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;The first-login race.&lt;/strong&gt; The install guide warns that whoever reaches the registration page first becomes the admin, with root access to your server. Create your admin account right away, or pre-create it with the install variables.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Backups and restores.&lt;/strong&gt; Coolify's own docs say it plainly: "A backup is not a restore test." You need an S3 bucket, a schedule, a retention rule and an occasional practice restore.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Outages.&lt;/strong&gt; One server means one point of failure. When it goes down at 2 a.m., you're the on-call team.&lt;/li&gt;
&lt;/ol&gt;

&lt;h3&gt;
  
  
  A worksheet for your own time
&lt;/h3&gt;

&lt;p&gt;Use these as starting estimates and adjust them to your experience.&lt;/p&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Task&lt;/th&gt;
&lt;th&gt;First month&lt;/th&gt;
&lt;th&gt;Each month after&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;Create server, SSH, firewall, DNS, install Coolify&lt;/td&gt;
&lt;td&gt;2–4 h&lt;/td&gt;
&lt;td&gt;–&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Set up S3 backups and do one practice restore&lt;/td&gt;
&lt;td&gt;1–2 h&lt;/td&gt;
&lt;td&gt;0.5 h (restore test)&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;OS and Coolify updates, advisories, disk cleanup&lt;/td&gt;
&lt;td&gt;–&lt;/td&gt;
&lt;td&gt;0.5–1 h&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Something breaks&lt;/td&gt;
&lt;td&gt;–&lt;/td&gt;
&lt;td&gt;0–2 h&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;strong&gt;Total&lt;/strong&gt;&lt;/td&gt;
&lt;td&gt;&lt;strong&gt;3–6 h&lt;/strong&gt;&lt;/td&gt;
&lt;td&gt;&lt;strong&gt;1–3.5 h&lt;/strong&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;p&gt;Multiply the monthly hours by what an hour of your time is worth. At $30 an hour, even &lt;strong&gt;1 hour a month adds $30&lt;/strong&gt;, more than the whole self-hosted server bill. That's the real comparison.&lt;/p&gt;

&lt;p&gt;If you enjoy running servers, or you're learning, those hours aren't a cost. They're the point. That's a perfectly good reason to choose Coolify.&lt;/p&gt;

&lt;h2&gt;
  
  
  When Coolify wins on money: many small apps on one server
&lt;/h2&gt;

&lt;p&gt;The managed rows grow with every app. The self-hosted row is flat until the server is full.&lt;/p&gt;

&lt;p&gt;Using the numbers above (a $21.60 Droplet with backups vs $2.23 per always-on Hubfly space container):&lt;/p&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Small apps&lt;/th&gt;
&lt;th&gt;Hubfly space, all sharing one Nano Postgres&lt;/th&gt;
&lt;th&gt;Hubfly space, each with its own Nano Postgres&lt;/th&gt;
&lt;th&gt;Coolify, 2 GiB Droplet + backups&lt;/th&gt;
&lt;th&gt;Coolify, 4 GiB Droplet + backups&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;1&lt;/td&gt;
&lt;td&gt;$4.26&lt;/td&gt;
&lt;td&gt;$4.26&lt;/td&gt;
&lt;td&gt;$21.60&lt;/td&gt;
&lt;td&gt;$28.80&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;3&lt;/td&gt;
&lt;td&gt;$8.73&lt;/td&gt;
&lt;td&gt;$12.77&lt;/td&gt;
&lt;td&gt;$21.60&lt;/td&gt;
&lt;td&gt;$28.80&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;5&lt;/td&gt;
&lt;td&gt;$13.20&lt;/td&gt;
&lt;td&gt;$21.28&lt;/td&gt;
&lt;td&gt;$21.60&lt;/td&gt;
&lt;td&gt;$28.80&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;7&lt;/td&gt;
&lt;td&gt;$17.67&lt;/td&gt;
&lt;td&gt;$29.79&lt;/td&gt;
&lt;td&gt;$21.60&lt;/td&gt;
&lt;td&gt;$28.80&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;9&lt;/td&gt;
&lt;td&gt;$22.14&lt;/td&gt;
&lt;td&gt;$38.31&lt;/td&gt;
&lt;td&gt;$21.60&lt;/td&gt;
&lt;td&gt;$28.80&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;12&lt;/td&gt;
&lt;td&gt;$28.84&lt;/td&gt;
&lt;td&gt;$51.07&lt;/td&gt;
&lt;td&gt;$21.60&lt;/td&gt;
&lt;td&gt;$28.80&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;p&gt;On the smallest server Coolify supports, it breaks even at about &lt;strong&gt;5 apps that each need their own database&lt;/strong&gt;, or about &lt;strong&gt;9 apps sharing one&lt;/strong&gt;. Size the server for that many apps (4 GiB) and the break-even moves to about &lt;strong&gt;7&lt;/strong&gt; and &lt;strong&gt;12&lt;/strong&gt;. Two caveats keep this fair:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;The apps share 2 vCPUs and 2 GB on the Droplet, and Coolify uses some of that itself.&lt;/strong&gt; Nine always-on 512 MB containers on Hubfly space get 4.5 vCPUs and 4.5 GB between them; nine 512 MB apps won't fit in 2 GB next to Coolify. In practice, budget a 4 GiB Droplet ($24, or $28.80 with weekly backups) for that many apps, which moves the break-even point further out.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Staging and hobby apps don't need to run all night.&lt;/strong&gt; With Auto Sleep on, a 0.5 vCPU / 512 MB Hubfly space container shows &lt;strong&gt;$1.14 a month&lt;/strong&gt; in the cost panel, which pushes the break-even point further out.&lt;/li&gt;
&lt;/ul&gt;

&lt;h2&gt;
  
  
  Which should you pick?
&lt;/h2&gt;

&lt;p&gt;&lt;strong&gt;Pick Coolify self-hosted if:&lt;/strong&gt;&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;You run several small apps (about 5–7 if each needs its own database, about 9–12 if they share one, depending on server size) and want one flat bill.&lt;/li&gt;
&lt;li&gt;You already maintain Linux servers, or you want to learn.&lt;/li&gt;
&lt;li&gt;You need full control over where data lives, or to run on hardware you own.&lt;/li&gt;
&lt;li&gt;You'll actually set up S3 backups and test a restore.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;&lt;strong&gt;Pick Coolify Cloud if:&lt;/strong&gt; you like Coolify's workflow and own servers, but don't want to babysit the dashboard itself.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Pick Railway or Render if:&lt;/strong&gt; you want an established managed platform, you rely on one of its specific features, and the bill fits. Render's migration credits can make a move nearly free for a larger team.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Pick Hubfly space if:&lt;/strong&gt; you want managed containers with the lowest bill in this comparison for one or two small apps, a price you can see before you deploy, and a monthly budget cap per project. Just plan your own database exports until automatic backups ship.&lt;/p&gt;

&lt;p&gt;&lt;a href="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Fts606jxjoufgbovnsjh0.png" class="article-body-image-wrapper"&gt;&lt;img src="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Fts606jxjoufgbovnsjh0.png" alt="Project budget cap set to $10, with the projected monthly cost shown" width="485" height="420"&gt;&lt;/a&gt;&lt;/p&gt;

&lt;p&gt;&lt;em&gt;A project budget cap sets a hard monthly limit for the project, with emails at 80% and 90%, so a mistake can't run up a surprise bill.&lt;/em&gt;&lt;/p&gt;

&lt;h2&gt;
  
  
  What can go wrong
&lt;/h2&gt;

&lt;p&gt;&lt;strong&gt;1. "My Coolify server ran out of disk."&lt;/strong&gt; Old images, build caches and local backups pile up under &lt;code&gt;/data/coolify&lt;/code&gt; and Docker's own folders. Set backup retention in Coolify, upload backups to S3 with "Delete after S3 upload", and prune unused images on a schedule.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;2. "My backup job says Success but I can't restore."&lt;/strong&gt; A file existing isn't proof it restores. Restore into a throwaway database once a month and point a copy of your app at it.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;3. "My managed bill is higher than the table."&lt;/strong&gt; Usage-billed platforms charge for what you actually run. A bigger instance, a second replica or a chatty worker changes the math. Check each platform's cost estimate before deploying, and set a spending cap where the platform offers one.&lt;/p&gt;

&lt;h2&gt;
  
  
  Try the managed side in a few minutes
&lt;/h2&gt;

&lt;p&gt;Deploying a container image on Hubfly space is short:&lt;/p&gt;

&lt;ol&gt;
&lt;li&gt;Create a project and pick a region. Set a monthly budget cap under &lt;strong&gt;Advanced Options&lt;/strong&gt; if you want a hard limit.&lt;/li&gt;
&lt;li&gt;Click &lt;strong&gt;Create → Create Container&lt;/strong&gt;, choose &lt;strong&gt;Docker image&lt;/strong&gt;, and enter your image, like &lt;code&gt;your-org/your-app:1.0&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;On &lt;strong&gt;Resources&lt;/strong&gt;, choose &lt;strong&gt;Dedicated Tier&lt;/strong&gt;, set CPU and memory, and turn &lt;strong&gt;Auto Sleep&lt;/strong&gt; off for an always-on app. The cost panel updates as you move the sliders.&lt;/li&gt;
&lt;li&gt;Click &lt;strong&gt;Deploy Container&lt;/strong&gt;. A small image is running in well under a minute.&lt;/li&gt;
&lt;li&gt;Open &lt;strong&gt;Network → Add Domain → Auto Endpoint&lt;/strong&gt; and pick your port. You get an HTTPS address like &lt;code&gt;your-app.eu1.hubfly.app&lt;/code&gt;, about a minute after clicking Deploy for a small image.&lt;/li&gt;
&lt;/ol&gt;

&lt;p&gt;&lt;a href="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Fy9zgdw39muckaim5t7is.png" class="article-body-image-wrapper"&gt;&lt;img src="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Fy9zgdw39muckaim5t7is.png" alt="A dedicated container running, with 1 vCPU and 1 GB" width="800" height="164"&gt;&lt;/a&gt;&lt;/p&gt;

&lt;p&gt;&lt;em&gt;The container page after deploy: status, tier and resources at a glance.&lt;/em&gt;&lt;/p&gt;

&lt;p&gt;&lt;a href="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2F2bhx2x3kpd31sgfpqe0x.png" class="article-body-image-wrapper"&gt;&lt;img src="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2F2bhx2x3kpd31sgfpqe0x.png" alt="The Network tab with an HTTPS subdomain routed to port 80" width="799" height="189"&gt;&lt;/a&gt;&lt;/p&gt;

&lt;p&gt;&lt;em&gt;Network → Add Domain creates an HTTPS subdomain with TLS on by default.&lt;/em&gt;&lt;/p&gt;

&lt;p&gt;For the database, create a &lt;strong&gt;Managed service&lt;/strong&gt; project, choose PostgreSQL and the Nano size, and copy the connection string into your app's environment variables. See &lt;a href="https://blog.hubfly.space/managed-postgresql-database-2-dollars-a-month?utm_source=devto&amp;amp;utm_medium=referral&amp;amp;utm_campaign=coolify-vs-railway-render-self-hosting-cost" rel="noopener noreferrer"&gt;how to get a managed PostgreSQL database for about $2 a month&lt;/a&gt;.&lt;/p&gt;

&lt;h2&gt;
  
  
  Takeaway
&lt;/h2&gt;

&lt;p&gt;Coolify is free software, not free hosting. For one or two small apps, a managed platform is often cheaper than the server Coolify needs, before you count a single hour of your time. Once you run roughly 5–7 small apps that each need their own database (or 9–12 that share one), and you're comfortable owning backups and updates, Coolify on one server becomes the cheaper, flexible choice.&lt;/p&gt;

&lt;p&gt;Read next:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;&lt;a href="https://blog.hubfly.space/fixed-vs-pay-as-you-go-hosting-break-even?utm_source=devto&amp;amp;utm_medium=referral&amp;amp;utm_campaign=coolify-vs-railway-render-self-hosting-cost" rel="noopener noreferrer"&gt;Fixed vs pay-as-you-go hosting: find your break-even point&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href="https://blog.hubfly.space/heroku-alternatives-2026-prices?utm_source=devto&amp;amp;utm_medium=referral&amp;amp;utm_campaign=coolify-vs-railway-render-self-hosting-cost" rel="noopener noreferrer"&gt;Best Heroku alternatives in 2026: 7 options and what they cost&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href="https://blog.hubfly.space/deploy-docker-compose-as-is-8-platforms-prices?utm_source=devto&amp;amp;utm_medium=referral&amp;amp;utm_campaign=coolify-vs-railway-render-self-hosting-cost" rel="noopener noreferrer"&gt;Deploy a docker-compose.yml as-is: 8 platforms compared&lt;/a&gt;&lt;/li&gt;
&lt;/ul&gt;

&lt;h2&gt;
  
  
  Go further on Hubfly space
&lt;/h2&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;Moving from Railway?&lt;/strong&gt; Follow &lt;a href="https://blog.hubfly.space/migrate-from-railway?utm_source=devto&amp;amp;utm_medium=referral&amp;amp;utm_campaign=coolify-vs-railway-render-self-hosting-cost" rel="noopener noreferrer"&gt;how to move your app from Railway to Hubfly space, step by step&lt;/a&gt;.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Store backups and files&lt;/strong&gt; in Hubfly space Storage, S3-compatible buckets at about $0.011 per GB-month. A Coolify backup bucket works too.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Deploy on every push&lt;/strong&gt; with &lt;a href="https://blog.hubfly.space/deploy-on-push-github-actions-webhook?utm_source=devto&amp;amp;utm_medium=referral&amp;amp;utm_campaign=coolify-vs-railway-render-self-hosting-cost" rel="noopener noreferrer"&gt;GitHub Actions and a deploy webhook&lt;/a&gt;.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;&lt;strong&gt;Run the numbers for your own app&lt;/strong&gt; with the &lt;a href="https://www.hubfly.space/pricing" rel="noopener noreferrer"&gt;Hubfly space pricing calculator&lt;/a&gt;, or &lt;a href="https://dashboard.hubfly.space" rel="noopener noreferrer"&gt;start free on Hubfly space&lt;/a&gt;: 360 hours a month, no card needed.&lt;/p&gt;

</description>
      <category>selfhosted</category>
      <category>devops</category>
      <category>docker</category>
      <category>webdev</category>
    </item>
  </channel>
</rss>
