Bitdoze

FastHTML Multi-Page Website: Complete Structure Tutorial

Thu, 13 Aug 2026 00:00:00 GMT

Python 3.10 or newer installed
`pip install python-fasthtml` (this tutorial targets v0.14.x)
A code editor (VS Code, Cursor, or similar)
Basic Python knowledge (functions, imports, decorators)
Terminal or command-line access

FastHTML is pre-1.0 and ships breaking changes between minor versions. Always pin the exact version in `requirements.txt` (e.g., `python-fasthtml==0.14.11`) and re-test after upgrading. Read the CHANGELOG before bumping. ## Creating a multi-page website with FastHTML We'll build a 3-page site (Home, About, Contact) step by step, using modern FastHTML idioms: `fast_app()` for app initialization, `Title()` tuples for page shells, and dataclass-based form binding with Post/Redirect/Get. The structure is modular: a `main.py` entry point, a `components.py` for shared UI, and a `pages/` directory for per-page content. ### Step 1: Project structure A clean directory layout keeps the project maintainable as it grows: ``` mywebsite/ ├── main.py # Application entry point and routing ├── components.py # Reusable header, footer, and layout ├── requirements.txt # Pin dependencies └── pages/ # Per-page content modules ├── __init__.py # Makes pages a Python package ├── home.py # Home page content ├── about.py # About page content └── contact.py # Contact page with form ``` Create a `requirements.txt` to pin the version: ``` python-fasthtml==0.14.11 ``` Each file has a clear role: - **`main.py`** handles routing (URL → handler) and starts the server. - **`components.py`** holds reusable UI pieces (header, footer, page layout) that appear on every page. - **`pages/`** contains one module per page. Each returns FT components for that page's content. - **`pages/__init__.py`** is an empty file that makes the directory a proper Python package. The advantages: separation of concerns, easy to find and update specific pieces, and straightforward to add new files to `pages/` as the site grows. ### Step 2: Reusable components (header, footer, layout) Create `components.py` with three functions: `header()`, `footer()`, and `page_layout()`. The update from older tutorials: we use `Title()` tuples instead of manual `Html(Head(...))` wrapping. FastHTML auto-wraps the tuple in a full HTML document including any `hdrs` you passed to `fast_app()`. **File: `mywebsite/components.py`** ```python from fasthtml.common import * from datetime import datetime def header(current_page="/"): """Navigation bar shared across all pages. Args: current_page: Current page path, used to highlight the active link. """ nav_items = [ ("Home", "/"), ("About", "/about"), ("Contact", "/contact"), ] nav_links = [] for title, path in nav_items: is_current = current_page == path link_class = "text-white hover:text-gray-300 px-3 py-2" if is_current: link_class += " font-bold underline" nav_links.append(Li(A(title, href=path, cls=link_class))) return Header( Div( A("MyWebsite", href="/", cls="text-xl font-bold text-white"), Nav(Ul(*nav_links, cls="flex space-x-2"), cls="ml-auto"), cls="container mx-auto flex items-center justify-between px-4 py-3", ), cls="bg-blue-600 shadow-md", ) def footer(): """Footer shared across all pages.""" current_year = datetime.now().year return Footer( Div( Div( P(f"\u00a9 {current_year} MyWebsite. All rights reserved.", cls="text-gray-500"), cls="mb-4", ), Div( A("Privacy Policy", href="#", cls="text-blue-500 hover:underline mr-4"), A("Terms of Service", href="#", cls="text-blue-500 hover:underline"), cls="text-sm", ), cls="container mx-auto px-4 py-6 text-center", ), cls="bg-gray-100 mt-8", ) def page_layout(title, content, current_page="/"): """Wraps page content with header, footer, and meta tags. Returns a tuple that FastHTML auto-wraps into a full HTML document. The Tailwind CDN script and viewport meta are injected here for simplicity in this tutorial. """ return ( Title(title), Meta(name="viewport", content="width=device-width, initial-scale=1.0"), Meta(name="description", content=f"{title} - MyWebsite built with FastHTML"), Script(src="https://cdn.tailwindcss.com"), header(current_page), Main( Div(content, cls="container mx-auto px-4 py-8"), cls="min-h-screen", ), footer(), ) ``` What changed from older tutorials: 1. **`datetime.now().year`** instead of hardcoding `2025`. 2. **`page_layout` returns a tuple**: `(Title(...), Meta(...), header(...), Main(...), footer())`. FastHTML sees this tuple and wraps it in `Html(Head(...), Body(...))` automatically. No need for manual `Html(Head(Title(...)))`. 3. **Tailwind CDN script stays in `page_layout`** for simplicity. In production you'd move it to `fast_app(hdrs=...)` instead (see Production notes below). Tailwind's own docs state the Play CDN "is designed for development purposes only, and is not intended for production." The browser console will also warn you. For production, build a static CSS file with `npx @tailwindcss/cli -o public/styles.css` and serve it via a `` tag, or use FastHTML's default Pico CSS for zero-build styling. ### Step 3: Individual page content Create the page modules inside `pages/`. Start with an empty `pages/__init__.py` (just `touch pages/__init__.py`), then add each page. **File: `mywebsite/pages/home.py`** ```python from fasthtml.common import * def home(): """Home page content.""" return Div( # Hero section Div( H1("Welcome to MyWebsite", cls="text-4xl font-bold text-gray-800 mb-4"), P("Build web applications with FastHTML and Python.", cls="text-xl text-gray-600 mb-6"), Div( A("Get Started", href="/about", cls="bg-blue-600 hover:bg-blue-700 text-white font-bold py-2 px-4 rounded mr-4"), A("Learn More", href="/contact", cls="bg-gray-200 hover:bg-gray-300 text-gray-800 font-bold py-2 px-4 rounded"), cls="flex", ), cls="py-12 text-center", ), # Features section Div( H2("Key Features", cls="text-3xl font-bold text-center mb-8"), Div( Div( H3("Easy to Learn", cls="text-xl font-semibold mb-2"), P("Built on Python, making web development accessible to everyone.", cls="text-gray-600"), cls="bg-white p-6 rounded-lg shadow-md", ), Div( H3("Highly Productive", cls="text-xl font-semibold mb-2"), P("Create web applications faster with fewer lines of code.", cls="text-gray-600"), cls="bg-white p-6 rounded-lg shadow-md", ), Div( H3("Scalable", cls="text-xl font-semibold mb-2"), P("Easily expand your application as your needs grow.", cls="text-gray-600"), cls="bg-white p-6 rounded-lg shadow-md", ), cls="grid grid-cols-1 md:grid-cols-3 gap-6 mb-12", ), cls="py-8", ), ) ``` **File: `mywebsite/pages/about.py`** ```python from fasthtml.common import * def about(): """About page content.""" return Div( H1("About Us", cls="text-3xl font-bold text-gray-800 mb-6 text-center"), Div( Div( H2("Our Story", cls="text-2xl font-semibold mb-4"), P("MyWebsite was created to help developers build " "web applications using Python. Our mission is to make " "web development accessible, enjoyable, and productive.", cls="text-gray-600 mb-4"), P("We believe that Python developers should be able to create " "stunning web applications without having to learn multiple " "languages and frameworks.", cls="text-gray-600 mb-4"), cls="mb-8", ), Div( H2("Our Team", cls="text-2xl font-semibold mb-4"), Div( Div( H3("Jane Doe", cls="text-xl font-semibold"), P("Founder & CEO", cls="text-gray-500 italic mb-2"), P("Python enthusiast with 15 years of experience in web development.", cls="text-gray-600"), cls="bg-white p-4 rounded shadow-md", ), Div( H3("John Smith", cls="text-xl font-semibold"), P("CTO", cls="text-gray-500 italic mb-2"), P("Full-stack developer with a passion for clean, maintainable code.", cls="text-gray-600"), cls="bg-white p-4 rounded shadow-md", ), cls="grid grid-cols-1 md:grid-cols-2 gap-6", ), ), ), ) ``` **File: `mywebsite/pages/contact.py`** ```python from fasthtml.common import * def contact(): """Contact page content with a form.""" return Div( H1("Contact Us", cls="text-3xl font-bold text-gray-800 mb-6 text-center"), Div( # Contact info Div( H2("Get in Touch", cls="text-2xl font-semibold mb-4"), P("We'd love to hear from you! Use the form or the " "information below to reach out.", cls="text-gray-600 mb-4"), Div( P(Strong("Email: "), "info@mywebsite.com", cls="mb-2"), P(Strong("Phone: "), "+1 (555) 123-4567", cls="mb-2"), P(Strong("Address: "), "123 Web Street, Internet City, 10101", cls="mb-2"), cls="mb-6", ), cls="mb-8 md:pr-8", ), # Contact form Div( H2("Send a Message", cls="text-2xl font-semibold mb-4"), Form( Div( Label("Name", For="name", cls="block text-gray-700 mb-1"), Input(type="text", id="name", name="name", placeholder="Your name", cls="w-full px-3 py-2 border rounded focus:outline-none focus:ring focus:border-blue-500"), cls="mb-4", ), Div( Label("Email", For="email", cls="block text-gray-700 mb-1"), Input(type="email", id="email", name="email", placeholder="Your email", cls="w-full px-3 py-2 border rounded focus:outline-none focus:ring focus:border-blue-500"), cls="mb-4", ), Div( Label("Message", For="message", cls="block text-gray-700 mb-1"), Textarea(id="message", name="message", placeholder="Your message", rows=5, cls="w-full px-3 py-2 border rounded focus:outline-none focus:ring focus:border-blue-500"), cls="mb-6", ), Button("Send Message", type="submit", cls="bg-blue-600 hover:bg-blue-700 text-white font-bold py-2 px-4 rounded"), action="/submit-contact", method="post", cls="bg-white p-6 rounded-lg shadow-md", ), ), cls="md:flex", ), ) ``` If you've built HTML forms before, this is straightforward Python. Each function returns FT components that render to standard HTML. The form `action` points to `/submit-contact`. We'll handle that POST in the next step. For adding contact forms to other types of sites, see [adding a contact form to static websites](/add-contact-form-static-websites/). ### Step 4: Routing in the main application Here's where the modern FastHTML idioms matter. The updated `main.py` uses `fast_app()` instead of `FastHTML()`, `@rt` instead of `@app.get`, a real 404 handler, and no `if __name__` guard. **File: `mywebsite/main.py`** ```python from fasthtml.common import * from dataclasses import dataclass from pages.home import home as home_page from pages.about import about as about_page from pages.contact import contact as contact_page from components import page_layout # --- 404 handler (defined before fast_app so we can pass it in) --- def not_found(req, exc): error_content = Div( H1("404 - Page Not Found", cls="text-3xl font-bold text-gray-800 mb-4"), P("Sorry, that page doesn't exist.", cls="text-xl text-gray-600 mb-6"), A("Return Home", href="/", cls="bg-blue-600 hover:bg-blue-700 text-white font-bold py-2 px-4 rounded"), cls="text-center py-12", ) return page_layout("404 Not Found - MyWebsite", error_content, current_page="/") # Initialize the app. # pico=False disables the default Pico CSS since we're using Tailwind. # Tailwind CDN is injected via page_layout() for this tutorial. # exception_handlers registers our 404 handler for real HTTP 404 status codes. app, rt = fast_app( pico=False, exception_handlers={404: not_found}, ) # --- Routes --- @rt("/") def get(): return page_layout("Home - MyWebsite", home_page(), current_page="/") @rt("/about") def get(): return page_layout("About Us - MyWebsite", about_page(), current_page="/about") @rt("/contact") def get(): return page_layout("Contact Us - MyWebsite", contact_page(), current_page="/contact") # --- Form handling with dataclass binding + PRG --- @dataclass class Contact: name: str email: str message: str @app.post("/submit-contact") def submit_contact(contact: Contact): # In a real app, save to DB or send email here. # contact.name, contact.email, contact.message are typed and validated. return RedirectResponse("/thanks", status_code=303) @rt("/thanks") def get(): thanks_content = Div( H1("Thank You!", cls="text-3xl font-bold text-gray-800 mb-4"), P("We've received your message and will respond soon.", cls="text-xl text-gray-600 mb-6"), A("Return Home", href="/", cls="bg-blue-600 hover:bg-blue-700 text-white font-bold py-2 px-4 rounded"), cls="text-center py-12", ) return page_layout("Thank You - MyWebsite", thanks_content, current_page="/contact") serve() ``` The previous tutorial used `@app.get("/{path:path}")` for 404 handling. That returns **HTTP 200 OK** with a page that *says* "404". Crawlers and monitoring tools see a successful response, which is wrong for SEO and alerting. Use `exception_handlers={404: handler}` passed to `fast_app()` to return a genuine 404 status code. The official docs are explicit: "Never write `if __name__ == '__main__'` since `serve` checks it internally." The guard is harmless but unnecessary and flagged as non-idiomatic. Just call `serve()` at module level. Key changes explained: 1. **`app, rt = fast_app(pico=False)`**: `fast_app()` is the modern initialization. It returns `(app, rt)` where `rt` is shorthand for `app.route`. By default it includes Pico CSS, htmx 2.x, and surreal.js headers. We pass `pico=False` because we're using Tailwind instead. 2. **`@rt("/")` decorator**: instead of `@app.get("/")`. The function name `get` maps to the HTTP method. Both styles work; `@rt` is the idiomatic shorthand. 3. **`exception_handlers={404: not_found}`**: registered at app creation. The handler receives `(req, exc)` and must return a response. FastHTML wraps the FT component in a full HTML doc automatically, and the response gets a real HTTP 404 status. 4. **`serve()` without a guard**: runs uvicorn on `0.0.0.0:5001` with live-reload by default. ### Step 5: Contact form with dataclass binding and PRG pattern The contact form in Step 4 uses two patterns worth understanding: **Dataclass binding**: instead of loose function parameters (`name: str, email: str, message: str`), we define a `@dataclass class Contact`. FastHTML resolves form fields to the dataclass constructor automatically. This gives you type validation and cleaner code. **Post/Redirect/Get (PRG)**: the POST handler returns `RedirectResponse("/thanks", status_code=303)` instead of rendering the thank-you page directly. If a user refreshes after a direct POST render, the browser re-submits the form. A 303 redirect to a GET endpoint makes refresh safe. After a successful form POST, the browser holds the POST request in its history. If the user hits refresh, the browser asks "Re-send form data?" or silently re-submits. With PRG, the POST returns a 303 redirect to a GET endpoint. The browser's address bar shows the GET URL, and refreshing just reloads that page. No duplicate submissions. This is a standard web pattern. The FastHTML community discussed it in [GitHub issue #389](https://github.com/AnswerDotAI/fasthtml/issues/389), and `RedirectResponse` is the documented way to do it. ### Step 6 — Running and testing your website Now let's run it: ```bash cd mywebsite pip install -r requirements.txt python main.py ``` You should see uvicorn start on `http://0.0.0.0:5001`. Visit: - `http://localhost:5001/` — Home page - `http://localhost:5001/about` — About page - `http://localhost:5001/contact` — Contact page with form Click the nav links to move between pages. The current page should be highlighted in the header. Submit the contact form — you should be redirected to `/thanks`. Refresh that page — no duplicate form submission. ## Organizing routes with APIRouter The pattern above (import page functions, define routes in `main.py`) works fine for small sites. When your project grows past 3-4 pages, FastHTML offers `APIRouter` — introduced in v0.8.0 — to let each module own its routes. Routes are defined in `main.py` by importing page functions: ```python # main.py from pages.home import home as home_page from components import page_layout app, rt = fast_app(pico=False) @rt("/") def get(): return page_layout("Home", home_page(), current_page="/") ``` This is the pattern from Steps 1-6. Works well for small projects. Each page module creates its own `APIRouter` and registers itself with the app: ```python # pages/home.py from fasthtml.common import * from components import page_layout ar = APIRouter() @ar("/") def get(): return page_layout("Home", home_content(), current_page="/") def home_content(): return Div( H1("Welcome to MyWebsite", cls="text-4xl font-bold text-gray-800 mb-4"), P("Build web applications with FastHTML and Python.", cls="text-xl text-gray-600 mb-6"), cls="py-12 text-center", ) ``` ```python # main.py from fasthtml.common import * from components import not_found from pages.home import ar as home_routes app, rt = fast_app( pico=False, exception_handlers={404: not_found}, ) home_routes.to_app(app) serve() ``` Each page module is self-contained — routes and content live together. The `main.py` just wires them to the app. **Prefix support**: `APIRouter("/blog")` adds a URL prefix to all routes in that module. Useful for namespacing, e.g., all blog routes live under `/blog/*` without repeating the prefix in every decorator. For a real-world example of `APIRouter` in a multi-page project, see [building a multi-page AI tools website with FastHTML](/fasthtml-complex-ai-tools/). ## Verify and troubleshoot After building the site, verify it works:

Visit `/`, `/about`, `/contact` — content renders correctly
`curl -i http://127.0.0.1:5001/nope` — returns `HTTP/1.1 404 Not Found` (not 200)
Submit the contact form — browser redirects to `/thanks` (check the URL bar)
Refresh the thank-you page — no duplicate form submission
Check browser console — no JS errors from Tailwind CDN

### Common errors and fixes | Symptom | Likely cause | Fix | |---|---|---| | `ModuleNotFoundError: No module named 'pages'` | Missing `pages/__init__.py` or wrong working directory | Create the empty `__init__.py`; run from project root | | 404 page returns HTTP 200 | Old catch-all `@app.get("/{path:path}")` still in code | Replace with `exception_handlers={404: handler}` | | Port 5001 already in use | Another process on the port | Kill it (`lsof -i :5001`) or set `PORT=8000` env var | | `AttributeError: 'NoneType'` on form submit | Missing `name` attribute on `` | Ensure inputs have `name="name"`, `name="email"`, etc. | | Tailwind styles not loading | Play CDN blocked or offline | Check browser network tab; use a local CSS build for reliability | ### Debug mode Pass `debug=True` to `fast_app()` to get detailed error pages in the browser: ```python app, rt = fast_app(pico=False, debug=True) ``` Never use this in production — it exposes stack traces to users. ### Testing with TestClient You can test routes without a browser using Starlette's `TestClient`: ```python from starlette.testclient import TestClient client = TestClient(app) print(client.get("/").status_code) # 200 print(client.get("/nope").status_code) # 404 print(client.post("/submit-contact", data={ "name": "Test", "email": "a@b.c", "message": "hi" }).status_code) # 303 ``` This is useful for CI or quick smoke tests after changes. ## Production and deployment notes The tutorial above is optimized for local development. Here's what changes when you deploy beyond localhost. ### Serving in production `serve()` is a dev-friendly wrapper. It binds `0.0.0.0:5001` with live-reload on by default. For production, use uvicorn directly behind a reverse proxy for TLS termination and multiple workers: ```bash uvicorn main:app --host 0.0.0.0 --port 8000 --workers 4 ``` Put Caddy, Nginx, or Traefik in front for automatic HTTPS. [Deploying a Python project with Dokploy](/dokploy-python-railpack-uv/) is one way to automate this on a VPS. ### CSS strategy The Tailwind Play CDN compiles CSS in the browser on every page load — fine for development, slow and unreliable in production. Options: 1. **Build a static CSS file**: `npx @tailwindcss/cli -o public/styles.css` and serve it via `fast_app(hdrs=(Link(rel="stylesheet", href="/styles.css"),))`. 2. **Use Pico CSS**: FastHTML's default. Zero build step, classless, looks decent out of the box. Drop `pico=False` and remove the Tailwind script. ### Static files `fast_app(static_path='public')` serves files from a `public/` directory automatically. Useful for images, CSS, and JS assets. ### Version pinning FastHTML is 0.x with frequent breaking changes. v0.14.1 removed several imports from `fasthtml.common`. Always pin `python-fasthtml` in `requirements.txt` and re-test before upgrading. ### Sessions and secrets `fast_app(secret_key="your-secret")` enables signed session cookies via Starlette's session middleware. Never hardcode secrets — use environment variables. ### Deploying to a VPS For affordable hosting, a [Hetzner Cloud VPS](https://go.bitdoze.com/hetzner) starts at around €4/month and runs a FastHTML app without issues. You can [run any Python app in Docker](/docker-run-python/) or set up a full deployment pipeline by [deploying a Python project with Dokploy](/dokploy-python-railpack-uv/). ## Extending your multi-page website The foundation is in place. Here's how to grow it: ### Adding more pages Create a new file in `pages/`, add a route (or `APIRouter`), and add a nav link in `components.py`. That's it. ### Adding dynamic content Fetch data from APIs, read from a database, or generate content based on user input. See [adding a SQLite database to your FastHTML app](/fasthtml-sqlite-db/) and [building an AI-powered web app with FastHTML and PydanticAI](/fasthtml-pydenticai-tools/) for concrete examples. ### Implementing user authentication For protected pages: login/register routes, session management, and redirects for unauthenticated users. Follow [adding user authentication to your FastHTML app](/fasthtml-user-auth/). ### Enhancing the UI Add HTMX interactions for partial page updates, Tailwind animations, and client-side form validation. [Building a multi-page AI tools website with FastHTML](/fasthtml-complex-ai-tools/) shows HTMX in action with a real project. ## Conclusion You've built a FastHTML multi-page website with: - **Modular project structure**: `main.py`, `components.py`, and per-page modules - **Reusable shared layout**: header, footer, and page shell in one place - **Modern FastHTML idioms**: `fast_app()`, `@rt`, `Title()` tuples - **Proper 404 handling**: `exception_handlers={404: handler}` returning real HTTP 404 - **Form processing**: dataclass binding with Post/Redirect/Get pattern - **A path to scale**: `APIRouter` for multi-file routing when the project grows The code in this tutorial targets FastHTML 0.14.x. Pin your version, read the CHANGELOG before upgrading, and check the Production notes before deploying.

Self-Hosted Shared Inbox for $5/Month: HQBase Review

Thu, 13 Aug 2026 00:00:00 GMT

Cloudflare account with a domain using Cloudflare DNS (nameservers pointed to Cloudflare)
Cloudflare Workers Paid plan ($5/mo, activate in your Cloudflare dashboard)
R2 subscription activated (even though it has a free tier, you must complete the R2 checkout in the dashboard)
Node.js 20+ and pnpm 11+ installed locally
Wrangler CLI authenticated (wrangler login)
An email address not on any domain connected to the workspace for the owner/recovery account

The owner's login email must NOT be on a domain you plan to connect to HQBase. If HQBase goes down, you need recovery access via an external email. Use a Gmail, Outlook, or another personal address as the owner account. This is enforced by design. For [Cloudflare DNS](https://www.bitdoze.com/traefik-wildcard-certificate/) setup, if your domain's nameservers aren't pointing to Cloudflare yet, you'll need to update them at your registrar and wait for the status to show "Active." This is typically the slowest step (can take hours). ### Deploy HQBase You can use the "Deploy to Cloudflare" button from the repo or deploy manually via Wrangler. **Option A: One-click deploy** Click the deploy button on the [HQBase GitHub repo](https://github.com/HQBase/hqbase). It'll prompt you to authenticate with Cloudflare and create the required resources. **Option B: Manual deploy via CLI** ```sh git clone https://github.com/HQBase/hqbase.git cd hqbase pnpm install wrangler login pnpm run deploy ``` The installer creates all resources (Worker, D1 database, R2 bucket, Queues), applies database migrations, verifies the signed release, and saves a non-secret deployment record. It installs the current signed stable release and refuses to overwrite a non-empty Worker unless it can verify a valid HQBase release. **Verify deployment:** After the command completes, visit the Worker URL shown in the output. You should see the HQBase setup wizard. **What failure looks like:** If you haven't activated Workers Paid or R2, the deploy will fail with binding errors. If your domain isn't on Cloudflare DNS, email routing setup will fail later. ### Configure email routing and domains The HQBase setup wizard walks you through adding your email domains. During this step, HQBase creates the required DNS records automatically: - **MX records** — point to Cloudflare's email receiving infrastructure - **SPF** — authorizes Cloudflare to send on your behalf - **DKIM** — signing key for outbound email authentication - **DMARC** — policy record for email authentication alignment HQBase also enables Email Routing with a catch-all rule that forwards all inbound mail to the Worker. HQBase's setup wizard creates MX, SPF, DKIM, and DMARC records automatically during domain configuration. After setup, verify them in your Cloudflare DNS dashboard under your domain's DNS settings. **Verify:** Check your Cloudflare dashboard → your domain → DNS records. You should see MX, SPF, DKIM, and DMARC entries. Cloudflare will show Email Routing as "Enabled" for the domain. **What failure looks like:** If Cloudflare shows "Authentication error" for Email Routing DNS, re-approve the Zone Settings / Edit permission in your Cloudflare API token settings. ### Create mailboxes and invite teammates Once domains are configured: 1. Create shared mailboxes (`support@yourdomain.com`, `sales@yourdomain.com`, etc.) 2. Set access levels for each mailbox (None / Read / Agent / Manager) 3. Invite teammates — they'll receive a password-setup link (fixed in v1.0.1 to properly reach the `/set-password` form) **Verify:** Send a test email to `support@yourdomain.com` from an external address (Gmail, etc.). It should land in the HQBase inbox within seconds. This validates the full inbound path: Email Routing catch-all → Worker → D1 index → R2 storage. ## HQBase access control: mailbox roles and workspace permissions This is one of HQBase's strongest features. The access model has two layers: ### Workspace roles | Role | Can do | |---|---| | **Owner** | Everything. Recovery account. Manager of every mailbox by default. Login email must be on a domain NOT in the workspace. | | **Admin** | Manage people, settings, and access — but cannot read a mailbox unless explicitly granted access. | | **Member** | Can only access mailboxes where they've been granted a role. | ### Mailbox access levels | Level | Capabilities | |---|---| | **None** | No access to the mailbox | | **Read** | Read, search, download messages | | **Agent** | Read + send, reply, mark read, star, archive, trash | | **Manager** | Agent + mailbox settings and deletion rules | The critical point: **the same access rules are enforced across the web app, REST API, and MCP server.** If a team member can't read `finance@`, their AI agent connected via MCP can't read it either. You can give an MCP connection fewer abilities than its user, but never more. This matters when thinking about [MCP servers vs native agent tools](https://www.bitdoze.com/mastra-tools-vs-mcp/). With HQBase, the permission boundary is enforced at the data layer, not bolted on as an afterthought in the AI integration. ![HQBase access control matrix showing Owner, Admin, Member roles against mailbox capabilities](../../assets/images/26/08/hqbase-access-control.webp) The same access rules apply everywhere — web UI, REST API, and MCP. If a user can't read a mailbox, their AI agent can't either. This is a meaningful security improvement over tools with separate AI integration layers. Additional safety: audit history records sensitive actions (without exposing email content, passwords, or tokens). Trash is auto-deleted after 30 days. Messages are otherwise kept indefinitely by default. ## Connect AI tools to HQBase over MCP HQBase ships an OAuth-protected MCP server, so [AI coding tools like Claude Code and Cursor](https://www.bitdoze.com/best-ai-coding-tools/) can search, read, draft, and send email on your behalf. ### MCP profiles | Profile | Endpoint | Capabilities | |---|---|---| | **Read-only** | `/mcp` | `list_mailboxes`, `search_messages`, `list_conversations`, `get_message`, `get_thread`, `get_attachment` | | **Mail actions** | `/mcp/full` | Everything above + `send_email`, `reply_to_message`, `forward_message`, draft CRUD, `update_message`, `update_conversation` | Switching from read-only to mail actions requires a new OAuth connection and approval. Scopes: `mail:read`, `mail:write`, `mail:send`, `offline_access`. ### OAuth flow HQBase uses Streamable HTTP with OAuth 2.0 discovery, dynamic client registration, authorization code flow with PKCE, and user consent. The OAuth relay at `auth.hqbase.io` only returns a short-lived authorization code to your Worker. It never exchanges the code or sees your access token or mail content. For organizations that block public OAuth apps, you can register a private Cloudflare OAuth client (Authorization Code + PKCE, no client secret required). ### Connecting a client Add HQBase as an MCP server in your client configuration. For Claude Code, add to your MCP settings: ```json { "mcpServers": { "hqbase": { "url": "https://your-worker.your-subdomain.workers.dev/mcp", "oauth": true } } } ``` For the full mail-actions profile, use `/mcp/full` instead of `/mcp`. HQBase docs explicitly warn that send/reply/forward can send more than once if an MCP client retries. Start with read-only mode and test thoroughly before enabling mail actions for production workflows. Do not blindly retry failed sends. **Other MCP limitations to know:** - Attachments via MCP are capped at **10 MiB** - No live push/streaming of new mail: you must poll via search or list - MCP cannot manage people, mailboxes, domains, setup, updates, audit, sessions, or secrets - HQBase does **not** ship a built-in LLM. It exposes mail to external AI tools via MCP (unlike Cloudflare Agentic Inbox, which has a built-in AI agent) ## HQBase ops: updates, backups, rollback and doctor HQBase treats operations seriously — signed releases, verification, backup, and rollback are all first-class CLI features. ### Updates The updater downloads the release, verifies the `stable.json` manifest (Ed25519 signature + SHA-256 digest), checks product/channel/version and database compatibility, then deploys. If an update fails, the updater prints exact recovery commands. Never skip the verification step. The signed manifest is what protects you from deploying a tampered or incompatible release. ### Backups ```sh pnpm hqbase -- backup ``` **Critical caveat:** this records D1 bookmarks, the active Worker version, and an R2 inventory. It does **not** download email or attachments to your local machine. It's a deployment snapshot, not an offline mail export. For offline copies, you'd need to export from R2 separately. Always run `backup` before any manual change. ### Rollback ```sh pnpm hqbase -- restore ``` Worker rollback and D1 restore are deliberately separate operations. D1 restore is **destructive** — it discards all mail received after the restore point. Never restore D1 casually. The recommended sequence: 1. Run `backup` first 2. Roll back the Worker 3. Only if necessary, restore D1 (understanding you'll lose newer messages) ### The doctor command ```sh pnpm hqbase -- doctor # diagnostics (read-only) pnpm hqbase -- doctor --repair --yes # fix detected issues ``` `doctor` checks version, database, Worker health, storage, queues, email domains, and update channel. Run it before and after any manual change. Restoring D1 discards all mail received after the restore point. Worker rollback and D1 restore are separate operations — never restore D1 without understanding you'll lose newer messages. Always back up first. Unlike VPS-based self-hosted email where you need [self-hosted monitoring tools](https://www.bitdoze.com/sever-monitoring/) to watch your mail server, HQBase removes the server entirely — Cloudflare handles the infrastructure health. You're monitoring bindings and configuration, not CPU and disk. ## HQBase vs Cloudflare Agentic Inbox vs FreeScout There are three main paths to "AI-aware shared email." They solve different problems. | Feature | HQBase | Cloudflare Agentic Inbox | FreeScout | Google Workspace | |---|---|---|---|---| | **Hosting** | Your Cloudflare account | Cloudflare-managed | Your VPS | Google SaaS | | **Cost (3 users, 3 mailboxes)** | ~$5/mo | TBD (beta/preview) | ~$5/mo VPS + your time | ~$21.60/mo | | **Mailbox-level RBAC** | Yes (None/Read/Agent/Manager) | No — single trust boundary | Basic roles | Yes | | **MCP / AI integration** | Built-in, scoped OAuth | Native (Cloudflare AI + built-in agent) | None (add-ons only) | None native | | **Data ownership** | Full (your Cloudflare account) | Cloudflare-managed | Full (your VPS) | Google | | **Open source** | Yes (AGPL-3.0) | Yes (Apache-2.0) | Yes (GPL-3.0) | No | | **Maturity** | Days old | Public preview, no releases | Years, established | Enterprise-grade | | **Mail server ops needed** | None | None | Yes (Postfix/relay + DB) | None | ### The sharpest difference: HQBase vs Agentic Inbox Agentic Inbox's README states directly: "Any user who passes the shared Cloudflare Access policy can access all mailboxes... There is no per-mailbox authorization." That single trust boundary is fine for a personal AI experiment, but it's a non-starter for teams. You can't give an AI agent access to `support@` while blocking it from `finance@`. HQBase solves this with proper per-mailbox RBAC, enforced consistently across web, API, and MCP. It also ships signed releases, rollback tooling, backup commands, and audit history — none of which Agentic Inbox provides. Agentic Inbox's advantage: it has a built-in AI agent (using Workers AI / kimi-k2.5) with auto-drafting. HQBase takes the opposite approach — no built-in LLM, but full MCP support so you bring your own AI tools. ### HQBase vs FreeScout FreeScout is the battle-tested self-hosted option (PHP, GPL-3.0, years of production use). But you're running a VPS, a database, and an SMTP relay. That's more moving parts, more things to patch, and more things to break. HQBase eliminates all of that by running on Cloudflare's serverless stack. If you're already invested in VPS-based self-hosting and want the full control, FreeScout makes sense. If you want fewer moving parts and a flat $5/month bill with no server maintenance, HQBase is the simpler path. ## HQBase limitations and caveats before you rely on it Be honest about the trade-offs: 1. **Brand-new project.** Well-architected and tested, but no production track record yet. Small team, fast-moving. Re-check the GitHub repo before adopting for anything critical. 2. **Cloudflare lock-in.** Requires Cloudflare DNS, Workers Paid, Email Routing, and Email Sending. You cannot run this on AWS, GCP, or a VPS. If you leave Cloudflare, you leave HQBase. 3. **Email Sending is beta.** Pricing, limits, and deliverability may change. Cloudflare auto-configures SPF/DKIM/DMARC, but the service is young. Monitor deliverability over the first few weeks. 4. **AGPL-3.0 license.** If you modify HQBase and offer it as a service, you must release your changes under AGPL. Fine for internal use — understand the implications for commercial products. 5. **"Backup" is not offline mail export.** The backup command snapshots deployment state (D1 bookmarks, Worker version, R2 inventory). It does not download email to your machine. Plan separately for compliance or data portability needs. 6. **No IMAP/POP.** All access is via the web UI, REST API, or MCP. No traditional email clients like Thunderbird or Apple Mail. 7. **MCP limitations.** 10 MiB attachment cap, no live push notifications for new mail (must poll), and double-send risk on retries. ## Verification checklist: is your inbox working? Run through this after setup and after any manual change:

Send a test email to support@yourdomain.com → confirm it lands in the HQBase inbox (validates Email Routing catch-all + D1 + R2)
Reply from the shared mailbox → check received headers for passing SPF/DKIM/DMARC (look for "signed-by" in Gmail, or test at mail-tester.com)
Run pnpm hqbase -- doctor and confirm all checks pass
Run pnpm hqbase -- backup and note the Worker version + D1 bookmark
Connect an MCP client in read-only mode → confirm list_mailboxes and search_messages return expected data
(Optional) Re-connect MCP with Mail actions → draft and send a test reply
Check Cloudflare dashboard: Worker analytics, D1 metrics, R2 bucket, Queue health
Confirm Email Sending is enabled and check the first outbound emails for deliverability

## FAQ The base HQBase software is free (AGPL-3.0). Your only cost is Cloudflare Workers Paid ($5/mo) plus any overage from Email Sending (first 3,000 emails/month are free, then $0.35/1,000). For most small teams with 3 mailboxes and a few hundred emails, the total stays at ~$5/month. Optional paid setup or support may be offered separately but doesn't gate any product features. No. HQBase requires Cloudflare to manage DNS for your email domains (for Email Routing and Sending). If your domain's nameservers point to Google or Microsoft, you'd need to migrate DNS to Cloudflare first. The owner/recovery email must also be on a domain NOT connected to the workspace. Email files and attachments are stored in Cloudflare R2, and the searchable index lives in Cloudflare D1. Cloudflare encrypts data at rest by default. However, HQBase itself doesn't add a separate application-level encryption layer. Your data's security depends on your Cloudflare account security — enable 2FA and use API tokens with minimal scopes. HQBase gives you per-mailbox RBAC (Read/Agent/Manager), so you can give an AI agent access to support@ but not finance@. Cloudflare's Agentic Inbox uses a single trust boundary — all mail is accessible or none is. HQBase is also fully open source (AGPL-3.0) and self-hosted in your account, while Agentic Inbox is a Cloudflare-managed service. If you need granular team permissions and data ownership, HQBase is the stronger choice. If you want a built-in AI agent with auto-drafting and don't need per-mailbox control, Agentic Inbox might be simpler. HQBase's `backup` command records deployment state (D1 bookmarks, Worker version, R2 inventory) but does not download email to your local machine. To export mail, you'd need to access the R2 bucket directly and copy the raw email files. There's no built-in one-click export to MBOX or EML format as of v1.0.1. Plan for this if compliance or data portability matters to your team. ## Updates | Date | Change | |---|---| | **2026-08-13** | Article published. HQBase v1.0.1. Cloudflare Email Sending in public beta. | ## Wrapping up HQBase is a genuinely different approach to shared team email. Serverless, open-source, with real per-mailbox access control and MCP integration — all for about $5/month with unlimited seats and mailboxes. The trade-off is hard Cloudflare platform lock-in and a brand-new project with no production track record. For teams already on Cloudflare who want to eliminate mail-server ops and flatten per-seat email costs, it's worth evaluating. Start with read-only MCP, run `doctor` regularly, and back up before every change. The cost math is hard to argue with: $5/month flat vs $7+/user/month on Google Workspace, with better AI integration and full data ownership. Just understand what you're signing up for — Cloudflare is the platform, Email Sending is beta, and the project is days old.

Best AI Coding Tools and Agents in 2026 (Compared)

Wed, 12 Aug 2026 00:00:00 GMT

import YouTubeEmbed from "../../components/widgets/YouTubeEmbed.astro"; import Notice from "../../components/widgets/Notice.astro"; import ListCheck from "../../components/widgets/ListCheck.astro"; import Tabs from "../../components/widgets/Tabs.astro"; import Tab from "../../components/widgets/Tab.astro"; import Accordion from "../../components/widgets/Accordion.astro"; import Button from "../../components/widgets/Button.astro"; The AI coding tools market has shifted hard since last year. What used to be autocomplete and chat-in-the-sidebar is now agentic coding: multi-file autonomous edits, cloud agents that open PRs, and issue-to-production flows. The best AI coding tools in 2026 don't just suggest the next line; they refactor entire modules, run your test suite, and ship code while you review. If you're [getting started programming with AI](/ai-programming-beginners-guide/) or you've been using AI coding assistants for a while, the landscape looks very different now. Three new players (Claude Code, OpenAI Codex, and Google Antigravity) have joined GitHub Copilot and Cursor as the dominant AI coding agents. Most tools have moved to credit or usage-based billing. The real pain points have shifted from "will it generate good code?" to "how do I keep my token bill sane?" and "how do I verify that the agent didn't break working code?" Agentic coding is now mainstream. Claude Code, Codex, and Antigravity handle multi-file edits autonomously. Most major tools (Copilot, Codex, Augment, Cursor, Replit) have moved to credit or usage-based billing. Three dominant new players entered the market alongside Copilot and Cursor. ## What are AI coding tools and assistants? AI coding tools use large language models to help you write, review, debug, and ship code. In 2026, they've evolved into four distinct categories, though the lines between them have blurred. Cursor has cloud agents, Copilot has cloud agents, and Codex ships as both a CLI and a cloud service. ### 1. Web tools Browser-based platforms for building apps without a local setup. These range from quick prototyping tools to full-stack builders that handle databases, auth, and deployment. **Examples:** v0.dev, bolt.new, lovable.dev, Replit, Tempo, Databutton ### 2. VS Code extensions AI agents that run inside VS Code or VS Code forks. This is where most professional developers interact with AI daily: inline completions, chat panels, and autonomous editing modes. **Examples:** GitHub Copilot, Cline, Kilo Code, Augment Code, [Amp Code (free AI coding agent)](/amp-code-free-ai-coding-agent/) ### 3. Dedicated AI-first IDEs Purpose-built editors with deep AI integration. They're optimized for AI-assisted workflows and tend to have the tightest model integration. **Examples:** Cursor, [Devin Desktop (formerly Windsurf)](https://go.bitdoze.com/windsurf), Trae, Zed, [Amazon's Kiro AI IDE](/kiro-ai-ide/) ### 4. Terminal and agentic CLIs The hottest category in 2026. These tools run in your terminal, edit across your entire codebase, run tests, and some spin up cloud VMs to produce PRs. The lines between "CLI" and "cloud agent" have blurred: Codex has both a local CLI and cloud background agents, Copilot has a cloud agent, and Claude Code runs sub-agents in parallel. **Examples:** Claude Code, OpenAI Codex, Google Antigravity, Aider, Goose, [OpenCode (open-source Claude Code alternative)](/opencode-setup-guide/), [Factory Droid CLI](https://go.bitdoze.com/droid-cli) | Category | Best for | Typical users | |----------|----------|---------------| | Web tools | Prototypes, MVPs, full-stack apps | Founders, product teams, non-coders | | VS Code extensions | Daily coding, existing workflows | Professional developers | | Dedicated IDEs | Full-time AI-assisted dev | Teams deep on AI integration | | Terminal and agentic CLIs | Autonomous edits, CI/headless, git workflows | Backend devs, DevOps, terminal-first engineers | ## What should you look for in AI code tools? The evaluation criteria have shifted. Code quality and language support still matter, but two new factors dominate the 2026 decision: how the billing works, and how much review work the tool creates for you. ### 1. Code generation and agentic capabilities - **Quality of output:** How accurate and maintainable is the generated code? - **Language and framework support:** Does it cover your stack? - **Context understanding:** Can it work across your codebase, not just the open file? - **Autonomous multi-file edits:** Can it refactor across files without hand-holding? - **Sub-agents and parallel tasks:** Can it run background jobs or spin up cloud VMs? - **Headless / CI mode:** Can it run in pipelines without a GUI? ### 2. Integration and workflow | Feature | Why it matters | |---------|---------------| | IDE integration | Works inside your existing editor | | Git support | Commits, branches, PRs handled by the agent | | Multi-file editing | Handles complex refactors | | Cloud agent | Spins up background VMs to produce PRs (Codex Cloud, Copilot cloud agent, Cursor Bugbot) | | CLI access | Terminal-first workflows for servers and CI | ### 3. AI model and performance - **Model quality:** GPT-5.5, Claude Opus 4.8, Gemini 2.5, and their cheaper variants (Haiku, GPT mini, Flash). - **Multi-model switching:** Copilot, Cursor, and Cline all let you pick models. This matters when you want cheap models for routine edits and powerful ones for complex refactors. - **Context window:** Claude Code's 1M-token context is a real differentiator for large codebases. - **Response time:** Codex Cloud runs at ~240 tokens/second, roughly 2.5x faster than Claude Opus. ### 4. Security and privacy - **Code privacy:** Where does your code go? Is it used for training? - **Training opt-out:** GitHub Copilot Free/Pro/Pro+ trains on your code by default (since April 2026). Business and Enterprise plans don't train. Cursor has privacy mode. Augment Business plans don't train either. This is a concrete, actionable differentiator. Check the settings. - **Network egress:** Sandboxed agents (Codex CLI blocks network by default) vs. open agents that can hit any endpoint. For more on protecting your site from AI scrapers, see our guide on [blocking AI crawlers](/block-ai-crawlers/). ### 5. Cost and usage-based billing This is the single biggest change in 2026. Most tools have moved from flat subscriptions to credit or token-based billing: - **GitHub Copilot** moved to "GitHub AI Credits" (1 credit = $0.01) on June 1, 2026. - **OpenAI Codex** moved to token-based billing on April 2, 2026. - **Augment Code** switched to credits in October 2025. - **Cursor** has on-demand usage billing on top of subscriptions. - **Replit** uses effort/credit-based pricing. Agentic coding burns 3-4x more tokens than autocomplete. Claude Code in particular uses significantly more tokens than Codex for similar tasks. If you're on API billing, set a hard spend limit on the provider's billing page. Prefer flat-rate Max plans for heavy use. They're far cheaper than equivalent API billing. For [cheaper GitHub Copilot alternatives](/github-copilot-alternatives-2026/), consider Cline or Kilo Code with your own API keys. Concrete advice: - Set **budget alerts.** Copilot has alerts at 75/90/100% of your budget. Enable them. - Prefer flat-rate plans (Copilot Max $100, Claude Max $100-200) over API billing for heavy use. - Use cheap models for routine tasks: Haiku, GPT mini, Gemini Flash for autocomplete and style edits. Save Opus/GPT-5.5 for complex refactors. - Unsupervised agents can burn 10-50x more tokens than interactive sessions. Don't let agents run wild. ### 6. Review burden and verification Here's the uncomfortable truth: AI coding agents break things. A 2026 study found that 75% of AI coding agents broke previously working code during CI workflows. Devin's vendor-claimed 67% PR merge rate dropped to 15% real-world success in independent testing (Answer.AI, 20 tasks).

Write tight, scoped tickets — don't give agents vague instructions
Require tests — agents should run and pass your test suite before you review
Review PRs line by line — don't trust "looks good" auto-approvals
Run the full test suite locally after the agent finishes
Scope API tokens to the minimum needed
Block network egress by default for sandboxed agents
Use CLAUDE.md, AGENTS.md, or .cursor/rules to pin build/test/lint commands

### 7. Enterprise requirements - **Team management:** Roles, permissions, seat limits - **Audit trails:** Activity logging for compliance - **SSO / SAML:** Required for most orgs - **Data residency:** EU/US options matter for GDPR ## Best AI coding tools and agents The lines between IDE, CLI, and cloud agent have blurred. Cursor has cloud agents, Copilot has a cloud agent, and Codex ships as both a local CLI and a cloud service. I've organized by category, but keep in mind that many tools now span multiple categories. ### Master comparison table | Tool | Category | Rating | Free option | Price range | Best for | |------|----------|--------|-------------|-------------|----------| | v0.dev | Web | ⭐⭐⭐⭐½ | Yes | Free / Team $30 | Full-stack app generation | | bolt.new | Web | ⭐⭐⭐⭐ | Yes | Free / Pro $25 | Rapid prototyping | | lovable.dev | Web | ⭐⭐⭐⭐ | Yes | Free / Pro $25 | Full-stack development | | Replit | Web | ⭐⭐⭐½ | Yes | Free / Core $20 | Learning and prototyping | | Tempo | Web | ⭐⭐⭐⭐ | Yes | Free / Pro $30 | Issue-to-PR automation | | Databutton | Web | ⭐⭐⭐⭐ | No | $20+ | Data-driven apps | | GitHub Copilot | VS Code | ⭐⭐⭐⭐½ | Yes | Free / Pro $10 | General coding (flagship) | | Cline | VS Code | ⭐⭐⭐⭐½ | Yes | Free (BYOK) | Autonomous coding agent | | Kilo Code | VS Code | ⭐⭐⭐⭐ | Yes | Free (BYOK) | Roo Code replacement | | Augment Code | VS Code | ⭐⭐⭐⭐ | Yes | Free / Indie $20 | Large codebases | | Amp Code | VS Code | ⭐⭐⭐⭐ | Yes | Free | Free agent in editor | | Cursor | IDE | ⭐⭐⭐⭐½ | Yes | Free / Pro $20 | AI-first development | | Devin Desktop | IDE | ⭐⭐⭐⭐ | Yes | Free / Pro $20 | Full-stack + cloud agent | | Trae | IDE | ⭐⭐⭐⭐ | Yes | Free / Pro $10 | Budget AI IDE | | Zed | IDE | ⭐⭐⭐⭐ | Yes | Free / AI $10 | Performance-focused | | Amazon Kiro | IDE | ⭐⭐⭐⭐ | Yes | Free / Pro $20 | Spec-driven development | | Claude Code | CLI | ⭐⭐⭐⭐½ | Limited | Pro $20 / Max $100 | Agentic terminal coding | | OpenAI Codex | CLI | ⭐⭐⭐⭐½ | Limited | Go $8 / Plus $20 | CLI + cloud agents | | Google Antigravity | CLI | ⭐⭐⭐⭐ | Yes | Free / AI Pro $20 | Google ecosystem | | Aider | CLI | ⭐⭐⭐⭐½ | Yes | Free (BYOK) | Git-based development | | Goose | CLI | ⭐⭐⭐⭐ | Yes | Free (BYOK) | Local/secure development | | OpenCode | CLI | ⭐⭐⭐⭐ | Yes | Free (BYOK) | Self-hosted agent | ### Web tools #### [v0.dev](https://v0.dev) (⭐⭐⭐⭐½) v0 has evolved from a UI component generator into a full-stack app builder. It now handles databases, tasks, and complete applications, not just React components. The credit model uses v0 Mini/Pro/Max model tiers, and you get $5 in credits per month on the free plan with a 7 messages/day limit. **Pricing (Aug 2026):** - **Free:** $0, $5 credits/month, 7 messages/day - **Team:** $30/user/month - **Business:** $100/user/month - **Enterprise:** Custom The old $20 "Premium" tier no longer exists. If you need more than the free tier, you're jumping to $30/user for Teams. **Best for:** Rapid UI prototyping, full-stack app generation, non-coders building MVPs. #### [bolt.new](https://bolt.new) (⭐⭐⭐⭐) StackBlitz's bolt.new lets you prompt, run, edit, and deploy full-stack apps directly in the browser. The pricing has been streamlined. The old Pro 50/100/200 tiers are gone. **Pricing (Aug 2026):** - **Free:** 300K daily tokens (1M monthly) - **Pro:** $25/month (10M tokens) - **Teams:** $30/member/month - **Enterprise:** Custom Tokens roll over for one month. That's a nice touch for intermittent use. **Best for:** Startups building MVPs, solo developers, proof-of-concept projects. #### [lovable.dev](https://lovable.dev) (⭐⭐⭐⭐) Lovable moved to a credit-based model. "Plan Mode" uses 1 credit per message. Credits expire after 2 months, so don't hoard them. **Pricing (Aug 2026):** - **Free:** 5 credits/day (~30/month) - **Pro:** $25/month (100 credits) - **Business:** $50/month - **Enterprise:** Custom **Best for:** Full-stack developers, agencies, rapid prototyping with team collaboration. #### [Replit](https://replit.com/ai) (⭐⭐⭐½) The biggest pricing shift of any tool in this article. Replit Core went from $25 to $20/month, and the new Replit Pro tier at $100/month targets power users. Replit Agent uses effort-based credits. **Pricing (Aug 2026):** - **Starter:** Free - **Core:** $20/month ($18 annual) - **Pro:** $100/month ($90 annual) - **Enterprise:** Custom **Best for:** Students, educators, quick prototyping, collaborative coding. #### [Tempo](https://tempo.new) (⭐⭐⭐⭐) Tempo pivoted from "React builder" to "AI agents that turn feedback and issues into reviewed PRs." That's a significant change. It's now competing with the agentic tools rather than the web builders. **Pricing (Aug 2026):** - **Free:** 30 prompts (5/day) - **Pro:** $30/month (150 prompts) - **Scale:** $50/month (250 prompts) - **Ultimate:** $100/month (555 prompts) - **Agent+:** $4,500/month **Best for:** Teams wanting automated issue-to-PR workflows. #### [Databutton](https://databutton.com) (⭐⭐⭐⭐) Databutton now tiers its offering around agent access plus varying levels of human support. **Pricing (Aug 2026):** - **Agent + Community:** $20/month - **Agent + Human advisor:** $699/month - **Agent + Human devs:** $1,999/month The jump from $20 to $699 is steep. You're paying for human expertise, not just the AI. **Best for:** Data-driven apps, analytics dashboards, Python/FastAPI backends. If you want a free alternative for building web apps without subscriptions, check out [Freebuff Web](https://go.bitdoze.com/freebuff) — a free AI app builder with no subscription or API keys needed. Web tools are best for prototyping and MVPs — they handle deployment, databases, and auth out of the box. But they lock you into their platform. For production apps you'll maintain long-term, a local IDE or CLI tool with proper version control is usually the better bet. Use web tools to validate an idea fast, then move to your own stack. ### VS Code extensions #### [GitHub Copilot](https://github.com/features/copilot) (⭐⭐⭐⭐½) — flagship GitHub Copilot is now the most feature-rich option in this category. The free tier is available to everyone (not just students/OSS), and the tool has expanded from autocomplete into a full agentic platform with cloud agents, code review, and third-party agent integration. **Key features:** - Multi-model support (Claude, GPT, Gemini — you pick per task) - Agent mode for autonomous multi-file edits - Cloud agent (spins up background VMs for complex tasks) - Copilot CLI (`gh copilot suggest "add rate limiting"`) - Code review on pull requests - Third-party agent integration (Claude Code, Codex) - `AGENTS.md` file for repo-level instructions **Pricing (Aug 2026):** - **Free:** $0 — 2,000 completions + 50 premium requests/month (for everyone) - **Pro:** $10/month - **Pro+:** $39/month - **Max:** $100/month - **Business:** $19/user/month - **Enterprise:** $39/user/month Copilot moved to usage-based billing with "GitHub AI Credits" (1 credit = $0.01) on June 1, 2026. If you're a heavy user, the [GitHub Copilot Pro plan](/github-copilot-complete-guide/) at $10 is still the best entry point. For heavier use, look at Max at $100 or consider [cheaper GitHub Copilot alternatives](/github-copilot-alternatives-2026/) like Cline. **Privacy note:** Copilot Free/Pro/Pro+ trains on your interactions by default since April 2026. Opt out in settings. Business and Enterprise plans don't train. **Best for:** Individual developers, enterprise teams, anyone wanting the broadest feature set in one tool. #### [Cline](https://cline.bot) (⭐⭐⭐⭐½) Cline remains free and open-source (Apache-2.0, ~66k GitHub stars). It's positioned as an "autonomous coding agent" available as an SDK, IDE extension, or CLI assistant. You only pay for the API tokens you use. Cline is free — you only pay for the API tokens you use. Point it at Ollama for zero cost. It supports Plan/Act modes for controlled autonomous editing. **Key features:** - Autonomous code generation with human-in-the-loop control - Multi-file editing and project-wide refactoring - Terminal command execution and browser automation - Custom tool creation via Model Context Protocol (MCP) - Plan/Act modes for step-by-step or fully autonomous operation **Best for:** Professional developers who want maximum control, self-hosters running local models, anyone allergic to subscriptions. #### [Kilo Code](https://kilo.ai) (⭐⭐⭐⭐) — new, replaces Roo Code Roo Code shut down on May 15, 2026 (repo archived read-only). Kilo Code is the open-source successor fork — a drop-in replacement. Free extension, you pay model API at cost with no markup. **Best for:** Former Roo Code users, developers wanting a free VS Code agent with BYOK (bring your own key). If you want to run with [affordable open-source LLM coding alternatives](/best-open-source-llms-claude-alternative/), Kilo Code pairs well with local models. #### [Augment Code](https://augmentcode.com) (⭐⭐⭐⭐) Augment switched to credit-based billing in October 2025. It's SOC 2 Type II certified and Business plans guarantee no AI training on your code. **Pricing (Aug 2026):** - **Free (trial):** Limited - **Indie:** $20/month - **Business:** $100/month flat (up to 50 seats) **Best for:** Enterprise teams managing large codebases, organizations needing SOC 2 compliance. #### [Amp Code](https://ampcode.com) (⭐⭐⭐⭐) — new Amp Code is a free AI coding agent that works directly in your editor. Good free-tier option if you want an agentic experience without paying for another subscription. See our full [Amp Code guide](/amp-code-free-ai-coding-agent/) for setup and features. **Best for:** Developers wanting a free agent experience in their editor. ### Dedicated AI-first IDEs #### [Cursor](https://www.cursor.com) (⭐⭐⭐⭐½) Cursor has expanded significantly. The Hobby tier is still free, and they've added Pro+ and Ultra tiers for power users. Cloud agents and Bugbot (autonomous bug-fixing) are the headline features now. **Key features:** - Built-in AI chat, inline editing, and agent mode - Cloud agents for background tasks - Bugbot for autonomous bug fixes - `.cursor/rules` file for pinning build/test/lint commands - VS Code extension compatibility - Usage-based on-demand billing **Pricing (Aug 2026):** - **Hobby:** Free - **Pro:** $20/month - **Pro+:** $60/month - **Ultra:** $200/month - **Teams:** $40/user/month - **Enterprise:** Custom **Best for:** Developers who want the tightest AI-IDE integration, teams doing full-time AI-assisted development. #### [Devin Desktop (formerly Windsurf)](https://go.bitdoze.com/windsurf) (⭐⭐⭐⭐) Windsurf was acquired by Cognition (the Devin company) in late 2025 (~$250M, per CNBC) and rebranded to Devin Desktop on June 2, 2026. The `windsurf.com/pricing` URL now redirects to `devin.ai/pricing`. It combines the IDE experience with Devin's cloud agent capabilities. **Pricing (Aug 2026):** - **Free:** $0 - **Pro:** $20/month - **Max:** $200/month - **Teams:** $80/month + $40/seat - **Enterprise:** Custom Devin cloud features use ACU-based billing (Agent Compute Units). If you're just using the IDE locally, the Pro $20 tier covers most needs. **Best for:** Full-stack developers, teams wanting IDE + cloud agent in one tool. #### [Trae](https://trae.ai) (⭐⭐⭐⭐) ByteDance's entry into the AI IDE space. The pricing is aggressive — $3/month for Lite and $10/month for Pro makes it the cheapest paid AI IDE. **Pricing (Aug 2026):** - **Free:** ~5,000 autocompletions/month + premium models - **Lite:** $3/month - **Pro:** $10/month (600+ premium requests) - **Enterprise:** Custom **Best for:** Budget-conscious developers, anyone wanting AI IDE features without the $20/month Cursor price tag. #### [Zed](https://zed.dev) (⭐⭐⭐⭐) The editor itself is free and open-source, built in Rust. Zed AI is the optional paid layer. **Pricing (Aug 2026):** - **Editor:** Free, open-source - **Zed AI:** $10/month (unlimited edit predictions + $5 of tokens, usage-based beyond) - **Business:** $30/seat/month **Best for:** Performance-focused developers, terminal enthusiasts, open-source contributors. #### [Amazon Kiro](https://kiro.dev) (⭐⭐⭐⭐) — new Kiro is Amazon's spec-driven agentic IDE, built on Code OSS. It replaces Amazon Q Developer (which stopped accepting new sign-ups on May 15, 2026). Kiro went GA in March 2026. The spec-driven approach is interesting — you write specs and Kiro generates implementation plans before writing code. Read more in our [Amazon Kiro AI IDE](/kiro-ai-ide/) deep dive. **Pricing (Aug 2026):** - **Free:** 50 credits/month - **Pro:** $20/month (1,000 credits) - **Pro+:** $40/month - **Pro Max:** $100/month - **Power:** $200/month - **Enterprise:** Custom **Best for:** AWS-heavy teams, developers wanting structured/spec-driven AI workflows. Cursor is the mature, feature-rich choice with the largest ecosystem. Devin Desktop brings cloud agent capabilities (autonomous PRs) into the IDE. Kiro's spec-driven approach suits teams that want structured, plan-first AI development. For most solo developers, Cursor Pro at $20 is the default pick. For teams already on AWS, Kiro's free tier is worth trying first. ### Terminal and agentic CLIs This is the hottest category in 2026. These tools run in your terminal, edit across your entire codebase, run tests, and some spin up cloud VMs to produce PRs. If you spend most of your day in a terminal, these are where the real productivity gains are. #### [Claude Code](https://docs.anthropic.com/en/docs/claude-code) (⭐⭐⭐⭐½) — new, flagship Anthropic's terminal-first agent. Claude Code has a 1M-token context window, handles multi-file refactors, and can spawn sub-agents for parallel tasks. Claude Opus 4.8 scored 88.6% on SWE-bench Verified (one of the highest published scores). **Key features:** - 1M-token context window (largest in class) - Multi-file refactors with full project understanding - Sub-agents for parallel task execution - `CLAUDE.md` file for repo-level rules - Headless/CI mode: `claude -p "fix the failing tests" --output-format json` **Pricing (Aug 2026):** - **Free:** Limited (with weekly caps) - **Pro:** $20/month (light use, included with Claude subscription) - **Max 5x:** $100/month - **Max 20x:** $200/month - **API:** Pay-as-you-go (Opus 4.8 ≈ $5/M input, $25/M output) Claude Code uses 3–4x more tokens than Codex for similar tasks. If you're on API billing, set a hard spend limit on the Anthropic billing page. For heavy use, the Max plans are far cheaper than equivalent API billing. **Install and get started:** ```bash npm install -g @anthropic-ai/claude-code cd your-project claude # interactive mode claude -p "explain this repo" --output-format json # headless/CI ``` Auth: `claude` prompts for Claude Pro/Max login, or set `ANTHROPIC_API_KEY` for API billing. **Best for:** Terminal-first developers, complex multi-file refactors, large codebases. #### [OpenAI Codex](https://github.com/openai/codex) (⭐⭐⭐⭐½) — new, flagship OpenAI's dual offering: an open-source CLI (`openai/codex`, Apache-2.0, ~105k GitHub stars, written in Rust) and Codex Cloud (parallel background VMs that produce PRs at ~240 tokens/second). GPT-5.5 scores 88.8% on Terminal-Bench 2.1. **Key features:** - Open-source CLI (Apache-2.0) - Codex Cloud: background VMs that produce PRs - ~240 tok/s throughput (roughly 2.5x faster than Claude Opus) - Sandbox network off by default (Docker/LocalStack blocked unless explicitly enabled) - `codex exec` for non-interactive / CI use **Pricing (Aug 2026):** - **Go:** $8/month - **Plus:** $20/month (bundled with ChatGPT Plus, 5-hour caps) - **Pro 5x:** $100/month - **Pro 20x:** $200/month - **Business:** $25/user/month - Token-based billing since April 2, 2026 **Install and get started:** ```bash npm install -g @openai/codex cd your-project codex # interactive TUI codex exec "fix the failing tests" # non-interactive / CI ``` Auth: `codex login` (ChatGPT sign-in) or set `OPENAI_API_KEY`. You can also [use the Codex app with any model](/codex-app-any-model/) for more flexibility. **Best for:** Developers wanting CLI + cloud agent flexibility, teams already in the OpenAI ecosystem, CI/CD pipelines. #### [Google Antigravity](https://antigravity.google) (⭐⭐⭐⭐) — new Google open-sourced Gemini CLI, then replaced it with Antigravity CLI on June 18, 2026. Antigravity is Google's agentic IDE/CLI, integrated into the Google ecosystem. **Pricing (Aug 2026):** - **Free preview:** $0 (Individual) - **AI Pro:** $20/month - **AI Ultra:** $100–$200/month - **Enterprise:** Custom **Best for:** Developers in the Google ecosystem, teams using Google Cloud, anyone wanting a free agentic CLI. #### [Aider](https://aider.chat/) (⭐⭐⭐⭐½) Still the best no-subscription, bring-your-own-key option. Aider is free, open-source, and pairs with any LLM you have API access to. The `aider-ce` community edition fork is also gaining traction. **Install and get started:** ```bash pipx install aider-chat cd your-project aider --model sonnet --watch-files ``` **Best for:** Terminal power users, git-focused developers, anyone who doesn't want another subscription. #### [Goose](https://goose-docs.ai) (⭐⭐⭐⭐) Block donated Goose to the Linux Foundation (AI Application Foundation). The repo moved to `aaif-goose/goose` (~52k GitHub stars). Still free and open-source (Apache-2.0), with desktop app, CLI, and API. **Best for:** Security-conscious teams, enterprise developers, DevOps engineers, local-first workflows. #### [OpenCode](https://opencode.ai) (⭐⭐⭐⭐) — new OpenCode is the most-starred open-source coding agent (~193k GitHub stars). It supports 75+ providers, is MIT-licensed, and runs as a terminal, desktop, or IDE agent. Perfect for the self-host, DIY crowd. **Install and get started:** ```bash curl -fsSL https://opencode.ai/install | bash ``` See our full [OpenCode setup guide](/opencode-setup-guide/) for VPS deployment and configuration. **Best for:** Self-hosters, developers wanting maximum provider flexibility, no-vendor-lock-in workflows. ```bash npm install -g @anthropic-ai/claude-code cd your-project claude ``` ```bash npm install -g @openai/codex cd your-project codex ``` ```bash pipx install aider-chat cd your-project aider --model sonnet --watch-files ``` ```bash curl -fsSL https://opencode.ai/install | bash cd your-project opencode ``` ## Cost control for AI coding agents This is the section I wish existed when I started using agentic tools. The shift to usage-based billing means your monthly bill can jump 10–50x if you let agents run unsupervised. Here's how to keep costs under control. **Set hard spend limits.** OpenAI and Anthropic both let you set monthly caps on the billing page. Do this before you start. Copilot has built-in alerts at 75/90/100% of your budget — enable them. **Prefer flat-rate plans for heavy use.** If you're a daily user, Max plans ($100–200/month) are far cheaper than equivalent API billing. The math only works in your favor on API billing if you're a light, occasional user. **Use cheap models for routine tasks.** Save Opus 4.8 and GPT-5.5 for complex refactors. For autocomplete, style edits, and boilerplate, use Haiku, GPT mini, or Gemini Flash. Most tools let you switch models per task. **Route between models.** If you want unified access to Claude Code, Codex, and Gemini CLI through a single interface, [Agent Router](https://go.bitdoze.com/agentrouter) can help — one API key, multiple backends. **Watch unsupervised agents.** An agent running in the background can burn through tokens fast. Check in frequently. Set time limits. Don't let agents iterate on failures endlessly. Run Cline or [OpenCode](https://go.bitdoze.com/opencode-go) + Ollama + a local model (Qwen 3.6, Llama 4) on your own hardware. Zero subscription, zero token costs. You pay for hardware and electricity only. See our guide on [affordable open-source LLM coding alternatives](/best-open-source-llms-claude-alternative/) for model recommendations. You can also explore [letting an AI assistant deploy Docker apps](/ai-docker-deploy-skill/) from your self-hosted setup. **Self-hosted / no-subscription stack:** - **Aider, Cline, OpenCode, Goose, Kilo Code, Continue** + Ollama = zero subscription cost - Point them at local models via `OLLAMA_API_BASE` or provider config - Works great for routine edits; switch to cloud models for complex refactors ## Why should you use AI coding assistant tools? The short version: they make you faster, but they don't make you worse — as long as you verify. ### Productivity gains GitHub's data shows developers using Copilot are up to 55% more productive on certain tasks. That figure comes from controlled studies and is still the most-cited benchmark in the space. In practice, the gains depend heavily on the task: boilerplate, tests, and documentation see the biggest speedups. Novel architecture decisions? Less so. ### Code quality AI tools standardize patterns, catch bugs early, and generate documentation you'd otherwise skip. They're particularly good at writing tests — a task most developers underinvest in. ### Learning and skill development Working with AI tools exposes you to patterns, libraries, and approaches you might not discover on your own. It's like pair programming with someone who's read every docs page (but occasionally hallucinates). ### Cost effectiveness With free tiers now available from Copilot, Cline, Kilo Code, and others, the barrier to entry is zero. For self-hosters, the Ollama + open-source agent stack costs nothing beyond hardware. Compare that to the $150–300/year most paid plans charge. ### The honest downsides AI coding agents break things. A 2026 study found 75% of agents broke previously working code during CI workflows. Review burden is real — you still need to read every line the agent writes. Token costs can surprise you if you're not paying attention. And privacy concerns are legitimate: some tools train on your code by default. Yes, but only with verification discipline and cost controls. Use them for boilerplate, tests, documentation, and rapid prototyping. For production code, treat agent output like a junior developer's PR — review it line by line, run the full test suite, and don't merge on autopilot. The productivity gains are real, but so are the failure modes. ## Conclusions No single tool wins everything. Here's my default recommendation for each use case: - **Best free option:** GitHub Copilot Free (for everyone) or Cline/Kilo Code + a free model. - **Best for agentic coding:** Claude Code or OpenAI Codex — pick based on ecosystem preference (Anthropic vs OpenAI). - **Best budget IDE:** Cursor Pro ($20) or Trae Pro ($10). - **Best for self-hosters:** [OpenCode](https://go.bitdoze.com/opencode-go) or Aider + Ollama. - **Best web tool:** v0.dev (full-stack) or bolt.new (prototyping).

Want the cheapest option? → Copilot Free / Cline + Ollama
Want maximum power? → Claude Code Max or Codex Pro
Want it in your terminal? → Codex CLI, Claude Code, or Aider
Want a web app builder? → v0.dev or bolt.new
Want zero subscription? → OpenCode or Aider + Ollama + local models
Want the best all-rounder? → GitHub Copilot Pro ($10) or Cursor Pro ($20)

The tools are only as good as your verification process. Set spend limits, write tight tickets, require tests, and review everything. The agents are fast — but you're the one responsible for what ships.

Creative Sound Blaster GS5 Review: Still Worth It in 2026?

Wed, 12 Aug 2026 00:00:00 GMT

import YouTubeEmbed from "../../components/widgets/YouTubeEmbed.astro"; import Notice from "../../components/widgets/Notice.astro"; import Button from "../../components/widgets/Button.astro"; import Tabs from "../../components/widgets/Tabs.astro"; import Tab from "../../components/widgets/Tab.astro"; import Accordion from "../../components/widgets/Accordion.astro"; **Rating: ⭐⭐⭐⭐ (4/5)** The [Creative Sound Blaster GS5](https://amzn.to/418lEIk) is a compact desktop soundbar that's been sitting on my desk for over 18 months now. When I first reviewed it, it was a ~$70 buy. Today it runs closer to $90 to $100. A lot has changed since then. Firmware updates fixed the biggest complaints (including the always-on LED display that annoyed everyone), but new issues have surfaced in long-term use. This updated review covers all of it. If you're looking for an affordable RGB gaming soundbar for a desktop setup, the GS5 still delivers good value, with some important caveats you need to know before buying.

How to Secure a VPS Server with CrowdSec (2026 Guide)

Tue, 11 Aug 2026 00:00:00 GMT

Install CrowdSec 1.7.8 and configure SSH log monitoring
Choose between nftables and iptables firewall bouncer
Allowlist your admin IP before enabling the bouncer (avoid lockout)
Handle Docker/Dokploy ports with the DOCKER-USER chain
Monitor Nginx access and error logs for web attack detection
Deploy the AppSec WAF for inline HTTP request inspection
Use the CrowdSec Console for centralized management

## What is CrowdSec and how can it help you? CrowdSec is an open-source, collaborative intrusion prevention system. It parses logs from services like SSH, Nginx, and custom applications, detects suspicious patterns using community-maintained scenarios, and pushes blocking decisions to remediation components called "bouncers." The anonymized attack data feeds back into a global threat intelligence network. Your server both consumes and contributes to that pool. ![Understanding CrowdSec](../../assets/images/25/02/crowdsec1.png) ### Understanding CrowdSec Three pillars make CrowdSec different from a basic fail2ban setup: 1. **Log parsing and detection.** CrowdSec ships with parsers for common services (SSH, Nginx, Apache, MySQL, and more). You install a collection, point it at log files, and it handles the rest. 2. **Bouncer-based remediation.** Decisions from the CrowdSec engine get pushed to bouncers, lightweight daemons that enforce blocks at the firewall, reverse proxy, or application layer. The firewall bouncer is the most critical; the Nginx bouncer adds AppSec WAF capabilities. 3. **Community threat intelligence.** CrowdSec shares anonymized attack data across its user base. When an IP brute-forces another CrowdSec user's server, your instance picks up that block decision too (if you subscribe to community blocklists via the CrowdSec Console). The [CrowdSec Hub](https://hub.crowdsec.net/) hosts collections, scenarios, parsers, and bouncers maintained by both the CrowdSec team and the community. ### Benefits of using CrowdSec for SSH protection SSH is the most common attack surface on a VPS. Leaving it exposed leads to brute force attempts, credential stuffing, and exploitation of weak configurations. CrowdSec improves SSH security by: 1. **Detecting intrusions.** Parsing SSH auth logs and identifying patterns like repeated failed login attempts. 2. **Blocking threats.** Pushing decisions to the firewall bouncer, which drops packets from flagged IPs. 3. **Providing visibility.** Metrics, alerts, and log entries that show exactly what was detected and what was blocked. 4. **Adapting dynamically.** Detection scenarios update through the CrowdSec Hub. No manual rule writing needed. ### Why choose CrowdSec over alternatives? | Feature | CrowdSec | Fail2Ban | Traditional Firewalls | |---------------------------|---------------------------|-----------------------------|-----------------------------| | **Community Intelligence**| Global threat sharing | None | None | | **Ease of Use** | Simple configuration | Moderate complexity | Manual configuration | | **Multi-service Support** | SSH, Nginx, AppSec, and more | Limited per service | Ports only | | **WAF Capability** | Yes (AppSec component) | No | No | | **Scalability** | Cloud-friendly | Local VPS only | Network-based | | **Real-time Blocking** | Fast with bouncers | Moderate | Reactive only | ## Install CrowdSec **Before you start, you need:** - A Linux VPS running Ubuntu 22.04/24.04 LTS or Debian 12+ - Root or sudo access - Ports 8080 (LAPI) and 6060 (metrics) available (or willingness to change them) If you don't have a VPS yet, you can grab [an affordable VPS from Hetzner](https://go.bitdoze.com/hetzner) or a [budget-friendly Hostinger VPS](https://go.bitdoze.com/hostinger-vps). ### Step 1: Add the CrowdSec repository ```bash curl -s https://install.crowdsec.net | sudo sh ``` This imports the CrowdSec GPG key and sets up the package repository. Expected output: ``` Detected operating system as ubuntu/24. Detected apt version as 2.7.14 Checking for gpg... Detected gpg... ... Installing /etc/apt/sources.list.d/crowdsec_crowdsec.list... ``` ### Step 2: Install the CrowdSec package ```bash sudo apt update && sudo apt install crowdsec ``` CrowdSec's local API uses port 8080 by default. If something else occupies that port, CrowdSec will fail to start. Check with `netstat -tulpn` before installing. If there's a conflict, see the next step. Sample installation output: ``` Need to get 62 MB of archives. After this operation, 255 MB of additional disk space will be used. ... Setting up crowdsec (1.7.8) ... Machine successfully added to the local API. API credentials written to '/etc/crowdsec/local_api_credentials.yaml'. ... Not attempting to start crowdsec, port 8080 is already used or lapi was disabled. ``` ### Step 3: Modify API port (if necessary) If the install output says port 8080 is already used, edit both config files: ```bash sudo nano /etc/crowdsec/config.yaml sudo nano /etc/crowdsec/local_api_credentials.yaml ``` Change `listen_uri` under `api` to a free port like 8081: ```yaml listen_uri: 127.0.0.1:8081 ``` Save, then start and verify: ```bash sudo service crowdsec start sudo service crowdsec status ``` Expected output: ``` ● crowdsec.service - Crowdsec agent Loaded: loaded (/lib/systemd/system/crowdsec.service; enabled; vendor preset: enabled) Active: active (running) since ... ``` ### Step 4: List installed collections ```bash sudo cscli collections list ``` ``` COLLECTIONS Name Status Version Local Path ───────────────────────────────────────────────────────────────────── crowdsecurity/linux enabled 0.3 ... crowdsecurity/sshd enabled 0.6 ... ``` The `crowdsecurity/sshd` collection confirms SSH monitoring is active. ## Installing the firewall bouncer (remediation) CrowdSec detects threats by analyzing logs. Bouncers enforce the decisions. They're lightweight daemons that block IPs at the firewall, reverse proxy, or application layer. The firewall bouncer is the most important one: it drops packets from flagged IPs before they reach any service. ### Choose your bouncer: iptables vs nftables Modern Linux distributions (Debian 12+, Ubuntu 24.04) use **nftables** as the native packet filter. iptables survives as a compatibility shim on these systems. CrowdSec offers separate bouncer packages for each backend. Run this to check which backend your system uses: ```bash iptables -V ``` If the output contains `nf_tables`, your system runs nftables natively. Use the nftables bouncer: ``` iptables v1.8.10 (nf_tables) ``` Install command: ```bash sudo apt install crowdsec-firewall-bouncer-nftables ``` This is the recommended path for new installs on Ubuntu 24.04+ and Debian 12+. If the output says `legacy` without `nf_tables`, use the iptables bouncer: ``` iptables v1.8.9 (legacy) ``` Install command: ```bash sudo apt install crowdsec-firewall-bouncer-iptables ``` This covers older Ubuntu 22.04 installs or systems explicitly configured for iptables. ### Lock yourself out? Allowlist your IP first If the firewall bouncer enables blocking on the INPUT chain and your current IP gets flagged (or you mistype something), you can lock yourself out of SSH permanently. Allowlist your admin IP first. CrowdSec 1.6.8 introduced a proper allowlist system. This is now the preferred method. It integrates with AppSec, scenarios, and console blocklists, and changes take effect immediately without restarting CrowdSec: ```bash cscli allowlist create admin_ips -d "My trusted admin IPs" cscli allowlist add admin_ips YOUR.HOME.IP.ADDRESS ``` Replace `YOUR.HOME.IP.ADDRESS` with your actual public IP. You can check it with `curl -s ifconfig.me` from another terminal. You can also add subnets for VPNs or monitoring services: ```bash cscli allowlist add admin_ips 10.0.0.0/8 ``` Verify the allowlist: ```bash cscli allowlist inspect admin_ips ``` ### Install the firewall bouncer After allowlisting your IP, install the appropriate bouncer (see the nftables vs iptables tabs above). For example, on a modern system: ```bash sudo apt install crowdsec-firewall-bouncer-nftables ``` Sample output: ``` Setting up crowdsec-firewall-bouncer (0.0.33) ... ``` The bouncer automatically registers itself with the CrowdSec LAPI and pulls decisions. ### Docker / Dokploy users: add DOCKER-USER chain Docker-published ports go through the FORWARD → DOCKER chains, not INPUT. The firewall bouncer's default configuration only inserts rules into INPUT, which means your Docker containers remain reachable from banned IPs. If you run Docker or [Dokploy](/dokploy-install/) to manage your containers, this is a critical gap. [Docker can bypass your firewall rules](/docker-bypasses-firewall/) without this fix. Edit the bouncer configuration: ```bash sudo nano /etc/crowdsec/bouncers/crowdsec-firewall-bouncer.yaml ``` Find the `iptables_chains` (or `nftables_chains`) section and add `DOCKER-USER`: ```yaml # For iptables mode: iptables_chains: - INPUT - DOCKER-USER # For nftables mode, add DOCKER-USER to the nftables_chains list ``` Restart the bouncer: ```bash sudo systemctl restart crowdsec-firewall-bouncer ``` This ensures CrowdSec blocks banned IPs from reaching your Docker containers too. For more on Docker networking and security, see [keeping your Docker server clean](/clean-docker-overlay2-dir/). ### Verify the bouncer installation ```bash sudo cscli bouncers list ``` Expected output: ``` ╭───────────────────────────────────────────────────────────────────────────────────────────────────────────────╮ │ Name IP Address Valid Last API pull Type Version │ ├───────────────────────────────────────────────────────────────────────────────────────────────────────────────┤ │ cs-firewall-bouncer-... 127.0.0.1 ✔️ 2026-06-20T07:00:00Z crowdsec-firewall-bouncer v0.0.33 │ ╰───────────────────────────────────────────────────────────────────────────────────────────────────────────────╯ ``` If the bouncer doesn't appear, restart the service and check logs: ```bash sudo systemctl restart crowdsec-firewall-bouncer sudo tail -f /var/log/crowdsec-firewall-bouncer.log ``` ### End-to-end smoke test Verify the bouncer actually blocks traffic. From your VPS, add a test decision for a harmless IP (don't use your own): ```bash sudo cscli decisions add -i 192.0.2.1 -t ban -r "smoke test" ``` Check that the IP appears in your firewall: ```bash sudo nft list sets | grep crowdsec # Then check the specific set: sudo nft list set inet crowdsec crowdsec-blacklists ``` You should see `192.0.2.1` in the set. ```bash sudo ipset list crowdsec-blacklists ``` You should see `192.0.2.1` as a member. Clean up the test decision: ```bash sudo cscli decisions delete -i 192.0.2.1 ``` IPv6 blocking works out of the box. CrowdSec's default configuration has `disable_ipv6: false`. Don't set it to true unless you've explicitly disabled IPv6 on your system. ## See what logs are monitored by CrowdSec CrowdSec creates an acquisition file at `/etc/crowdsec/acquis.yaml` that defines which log sources it monitors. View it: ```bash cat /etc/crowdsec/acquis.yaml ``` Sample output: ```yaml # Generated acquisition file - wizard.sh (service: ssh) / files : journalctl_filter: - _SYSTEMD_UNIT=ssh.service labels: type: syslog --- ``` This shows CrowdSec monitoring SSH via journald. If you installed additional collections (like Nginx), corresponding entries appear here too. ### CrowdSec log files CrowdSec generates its own logs for monitoring its operation: | File | Purpose | |-----------------------------------------|--------------------------------------------| | `/var/log/crowdsec.log` | Main engine log: detections, parsing | | `/var/log/crowdsec_api.log` | Local API (LAPI) requests and responses | | `/var/log/crowdsec-firewall-bouncer.log`| Firewall bouncer activity and errors | Watch the engine log in real time: ```bash sudo tail -f /var/log/crowdsec.log ``` ## Linking to the CrowdSec Console (optional) The CrowdSec Console is a cloud-based dashboard that provides centralized monitoring, attack visualization, and community-sourced threat intelligence across all your CrowdSec instances. The free tier includes 3 community blocklists with daily updates, centralized alert monitoring, and bouncer management. Premium starts at $31/month for real-time blocklist updates and custom blocklists. ### Step 1: Create an account Visit the [CrowdSec Console signup page](https://app.crowdsec.net/signup) and register with an email address. ### Step 2: Generate an enrollment token 1. Log in to the Console. 2. Navigate to **Security Engines** → **Engines**. 3. Click **Generate Enrollment Token**. 4. Copy the token. ### Step 3: Enroll your VPS ```bash sudo cscli console enroll --quick ``` The `--quick` flag (added in 1.7.8) speeds up enrollment. Sample output: ``` Successfully enrolled machine 'my-vps.example.com' to the Console ``` ### Step 4: Verify enrollment Return to the Console's **Engines** section. Your VPS should appear as an active engine. Once enrolled, you get centralized alert dashboards, attack trend graphs, and community intelligence feeds. This is useful for [monitoring your server health and security events](/beszel-uptime-kuma/) alongside CrowdSec's own metrics. ## Monitoring application logs (e.g., Nginx) CrowdSec can detect web attacks by analyzing Nginx logs: bot traffic, SQL injection probes, directory traversal, bad user agents, and more. For full protection, monitor **both** `access.log` and `error.log`. The current article's Nginx configuration only tracked `error.log`. Most HTTP attack detection scenarios (SQLi, path traversal, bad bots) parse `access.log`. Add both to get full coverage. ### Step 1: Install the Nginx collection ```bash sudo cscli collections install crowdsecurity/nginx ``` ``` INFO crowdsecurity/nginx installed successfully ``` ### Step 2: Update acquis.yaml Edit `/etc/crowdsec/acquis.yaml` and add the Nginx log entries: ```yaml filenames: - /var/log/nginx/access.log - /var/log/nginx/error.log - /home/*/logs/nginx/*.log labels: type: nginx --- ``` - `access.log` catches SQL injection probes, directory traversal, bad user agents, crawler abuse - `error.log` catches upstream failures, rate limiting, connection anomalies - The `/home/*/logs/nginx/*.log` wildcard covers virtual host logs (useful with Dokploy or similar setups) ### Step 3: Restart CrowdSec ```bash sudo systemctl restart crowdsec ``` ### Step 4: Verify Nginx monitoring is active ```bash sudo cscli alerts list sudo cscli decisions list ``` You should see entries related to Nginx scenarios. Tail the engine log to watch detections in real time: ```bash sudo tail -f /var/log/crowdsec.log ``` For more on managing web traffic and [blocking unwanted traffic at the application layer](/block-ai-crawlers/), CrowdSec's Nginx monitoring is the first step. The AppSec WAF below takes it further. ## Beyond the firewall: AppSec WAF protection The firewall bouncer blocks IPs at the packet level (reactive — after CrowdSec detects an attack in logs). The AppSec component inspects HTTP requests inline before they reach your application (proactive — blocks in real time). They complement each other. Keep both running. CrowdSec 1.6 introduced the **AppSec Component** — a full WAF that inspects HTTP requests inline using the Coraza engine (mod_security compatible). It detects SQL injection, XSS, path traversal, CVE exploits, and bad bots at the HTTP layer, before traffic reaches your application. ### What is the AppSec component? AppSec runs inside the Nginx/OpenResty/Traefik remediation component (bouncer). When an HTTP request arrives, the bouncer forwards it to the AppSec engine for inspection. If the request matches a rule (e.g., SQLi pattern, known CVE exploit), it gets blocked immediately — no log tail, no delay. This is fundamentally different from the log-based detection you've configured above. Log-based detection analyzes logs after the fact; AppSec blocks malicious requests before they touch your app. If you use [Traefik as your reverse proxy](/traefik-proxy-docker/), the Traefik bouncer supports AppSec too. ### Install and configure AppSec Install the AppSec virtual patching collection: ```bash sudo cscli collections install crowdsecurity/appsec-virtual-patching ``` CrowdSec 1.7.8 fixes CVE-2026-44982, a WAF bypass vulnerability via chunked transfer-encoding. If you run AppSec, updating to 1.7.8 is critical. Check your version: `cscli version`. Next, enable AppSec in the Nginx remediation component. Edit the Nginx bouncer configuration: ```bash sudo nano /etc/crowdsec/bouncers/crowdsec-nginx-bouncer.yaml ``` Ensure the AppSec section is enabled: ```yaml appsec: enabled: true # Path to the AppSec configuration # CrowdSec will use the default if not specified ``` If you don't have the Nginx bouncer installed yet (it's separate from the firewall bouncer): ```bash sudo apt install crowdsec-nginx-bouncer ``` Restart CrowdSec and Nginx: ```bash sudo systemctl restart crowdsec sudo systemctl restart nginx ``` Verify AppSec is active: ```bash sudo cscli appsec-configs list sudo cscli appsec-rules list ``` You should see the virtual patching rules loaded. These cover common web exploits and CVEs without you having to write custom rules. The AppSec component runs alongside your existing firewall bouncer — they don't interfere with each other. Firewall bouncer handles IP-level blocking (bulk bans from SSH brute force, community blocklists); AppSec handles HTTP-level inspection (inline blocking of web exploits). ## Useful CrowdSec commands After configuring CrowdSec, these commands help you monitor activity, manage blocks, and troubleshoot issues. ### View active decisions (current blocks/bans) ```bash sudo cscli decisions list ``` ``` ╭────────────┬─────────────┬────────────┬──────────────────────╮ │ IP │ Reason │ Action │ Expires at │ ├────────────┼─────────────┼────────────┼──────────────────────┤ │ 192.168.1.1│ ssh-bf │ ban │ 2026-06-20T12:00:00Z │ │ 203.0.113.5│ nginx-bot │ ban │ 2026-06-20T23:59:59Z │ ╰────────────┴─────────────┴────────────┴──────────────────────╯ ``` ### Check recent alerts ```bash sudo cscli alerts list ``` ``` ╭───────┬──────────────────────┬────────────────────┬──────────────╮ │ ID │ Scenario │ Source IP │ Created at │ ├───────┼──────────────────────┼────────────────────┼──────────────┤ │ 1 │ ssh-bf │ 203.0.113.5 │ 2026-06-20 │ │ 2 │ nginx-bad-user-agent │ 198.51.100.10 │ 2026-06-20 │ ╰───────┴──────────────────────┴────────────────────┴──────────────╯ ``` ### View security metrics ```bash sudo cscli metrics ``` This shows parsed log counts, detected threats, bouncer activity, and dropped connections. Use it to get a quick health check. ### Monitor logs in real time ```bash sudo tail -f /var/log/crowdsec.log ``` Useful for watching detections happen live and troubleshooting parser issues. ### List active detection scenarios ```bash sudo cscli scenarios list ``` ``` ╭───────────────────────────────────────┬────────╮ │ Name │ Status │ ├───────────────────────────────────────┼────────┤ │ crowdsecurity/ssh-bf │ enabled │ │ crowdsecurity/nginx-bad-user-agent │ enabled │ │ crowdsecurity/http-crawl-non_statics │ enabled │ ╰───────────────────────────────────────┴────────╯ ``` ### Add or remove a block manually **Block an IP:** ```bash sudo cscli decisions add -i -t ban -r "Manual ban" ``` **Unblock an IP:** ```bash sudo cscli decisions delete --ip ``` ### Using the allowlist system (cscli allowlist) The allowlist system (added in CrowdSec 1.6.8) is the preferred method for whitelisting trusted IPs. Unlike the older `cscli decisions add --type whitelist` approach, allowlists integrate with AppSec, scenarios, and console blocklists. Changes take effect immediately — no restart needed. ```bash # Create an allowlist cscli allowlist create my_allowlist -d "Trusted admin IPs" # Add individual IPs or subnets cscli allowlist add my_allowlist 203.0.113.5 cscli allowlist add my_allowlist 198.51.100.0/24 # Inspect what's in the allowlist cscli allowlist inspect my_allowlist ``` Practical examples: - Your home/office IP (dynamic DNS works too — update the allowlist when it changes) - VPN subnet for your admin access - Monitoring service IPs (Uptime Kuma, health checkers) ### Summary of useful commands | Command | Purpose | |-----------------------------------------|--------------------------------------------| | `sudo cscli decisions list` | List all active bans and blocks | | `sudo cscli alerts list` | View recent alerts triggered by attacks | | `sudo cscli metrics` | Display security metrics and performance | | `sudo tail -f /var/log/crowdsec.log` | Watch logs and detections in real time | | `sudo cscli scenarios list` | Show all active detection scenarios | | `sudo cscli decisions add` | Manually block specific IPs | | `sudo cscli decisions delete` | Remove a block for a specific IP | | `cscli allowlist create` | Create a new allowlist | | `cscli allowlist add` | Add an IP/subnet to an allowlist | | `cscli allowlist inspect` | View allowlist contents | ## Keeping CrowdSec updated and secure Keeping CrowdSec up to date is straightforward: ```bash sudo apt update && sudo apt upgrade crowdsec ``` CrowdSec 1.7.8 fixes two security vulnerabilities: CVE-2026-44982 (WAF bypass via chunked transfer-encoding) and CVE-2026-44981 (LAPI denial of service). If you run AppSec, updating is critical. If you only use the firewall bouncer, it's still strongly recommended. Additional notes: - **RE2 regex engine.** Since version 1.7.7, CrowdSec uses the RE2 regex engine by default on Linux, which brings significant performance improvements for log parsing. This matters on busy servers with high log volume. - **Security announcements.** Subscribe to CrowdSec's [GitHub releases](https://github.com/crowdsecurity/crowdsec/releases) or the [Discourse forum](https://discourse.crowdsec.net/) to stay informed about security patches. - **Bouncer updates.** Don't forget to update bouncers too: `sudo apt update && sudo apt upgrade crowdsec-firewall-bouncer-nftables` (or `-iptables`). The `cscli dashboard` command (Metabase-based local dashboard) was deprecated in CrowdSec 1.7.0. Use the CrowdSec Console instead — it's the officially supported way to visualize your security data. ## Conclusion CrowdSec gives you community-driven intrusion prevention that covers the full stack — SSH brute force blocking at the firewall level, Nginx log analysis for web attack detection, and inline HTTP inspection through the AppSec WAF. Here's what we walked through: - Installing CrowdSec 1.7.8 and configuring SSH log monitoring - Choosing between nftables (recommended for modern systems) and iptables firewall bouncer - Allowlisting your admin IP to prevent lockout - Configuring the DOCKER-USER chain for Docker/Dokploy hosts - Monitoring both Nginx access.log and error.log for web attack detection - Deploying the AppSec WAF for inline HTTP request blocking - Connecting to the CrowdSec Console for centralized management - Using allowlists and commands to manage CrowdSec day-to-day CrowdSec handles IP-level and HTTP-level threats. Pair it with a [layered security approach with DNS-level protection](/block-ads-malware-dns-protection/) for defense in depth. And if you run [server management panels that integrate with your security stack](/best-self-hosted-panels/), CrowdSec fits alongside those tools without conflicts. Keep it updated, watch your metrics, and explore the [CrowdSec Hub](https://hub.crowdsec.net/) for additional collections beyond SSH and Nginx — there are parsers for MySQL, PostgreSQL, WordPress, and dozens more services.

How To Do SSH Port Forwarding (SSH Tunneling) in Linux

Tue, 11 Aug 2026 00:00:00 GMT

import Notice from "@components/widgets/Notice.astro"; import Accordion from "@components/widgets/Accordion.astro"; import Tabs from "@components/widgets/Tabs.astro"; import Tab from "@components/widgets/Tab.astro"; SSH port forwarding (also called SSH tunneling) lets you route network traffic through an encrypted SSH connection. It solves a common operator problem: accessing a private database on a VPS, exposing a local dev server temporarily, or browsing securely over untrusted Wi-Fi, all without opening extra ports to the public internet. SSH port forwarding comes in three flavors (local, remote, and dynamic), each serving different scenarios. This guide covers all three, plus the operational bits that most tutorials skip: keeping tunnels alive with systemd, defining reusable tunnels in `~/.ssh/config`, chaining through jump hosts, and locking down forwarding permissions. ## Types of SSH port forwarding SSH port forwarding comes in three types, each serving specific use cases. Understanding their differences helps you pick the right one. ### Local port forwarding ![Local Port Forwarding](../../assets/images/25/02/local-port-forward.png) Local port forwarding lets you forward a port on your local machine to a specific port on a remote server. This is the most common type — use it to securely access services running on a remote server from your local machine. - **How it works**: Your local machine forwards traffic to a remote host via an SSH tunnel. - **Use case**: Securely accessing a remote MySQL database server from your local machine. ### Remote port forwarding ![Remote Port Forwarding](../../assets/images/25/02/remote-port-forward.png) Remote port forwarding does the opposite. It forwards a port on the remote server back to a specific port on your local machine. This allows a remote user or server to access services running locally on your system. - **How it works**: The remote server sends traffic back to the specified local machine and port via the SSH tunnel. - **Use case**: Exposing a local development web server so that remote stakeholders can access it. ### Dynamic port forwarding (SOCKS proxy) ![Dynamic Port Forwarding](../../assets/images/25/02/dinamic-port-forward.png) Dynamic port forwarding creates a SOCKS proxy server on your local machine that dynamically routes traffic to different destinations through the SSH tunnel. This is useful for secure web browsing or bypassing network restrictions. - **How it works**: A single local port is opened as a SOCKS proxy. You configure client applications (e.g., web browsers) to route traffic through this proxy. - **Use case**: Bypassing regional content restrictions or securing browsing on public Wi-Fi. ## Prerequisites Before you start, make sure you have: 1. **SSH access to a remote server**. A valid username and password, or preferably an SSH key pair. If you don't have a VPS yet, [Hetzner](https://go.bitdoze.com/hetzner) offers affordable cloud servers starting at ~4 EUR/month. See our guide on [setting up a VPS for remote access](/vps-ai-coding-setup/) if you're starting from scratch. 2. **OpenSSH installed** — Most Linux distributions ship it. Verify with: ```bash ssh -V ``` If not installed: `sudo apt install openssh-client` (Ubuntu/Debian) or `sudo yum install openssh` (CentOS). 3. **Network and firewall configuration** — Ensure the ports you plan to use aren't blocked. For remote port forwarding, the SSH server must allow it — check `AllowTcpForwarding` in `/etc/ssh/sshd_config`. 4. **Port knowledge** — Know which ports your services run on (MySQL: 3306, PostgreSQL: 5432, HTTP: 80, HTTPS: 443). Ed25519 has been the OpenSSH default since version 9.5 (October 2023). It's faster and produces smaller keys than RSA. If you're setting up SSH keys for the first time: ```bash ssh-keygen -t ed25519 -C "your-comment" ``` RSA-4096 still works for legacy systems. Use `ssh-keygen -t rsa -b 4096` only if your target server doesn't support Ed25519. For a full hardening walkthrough, see [hardening your SSH server](/secure-ssh-server-linux/). ## How to perform SSH port forwarding Every tunnel command below includes two flags you'll use every time: - **`-N`**: Do not execute a remote command. Without this, SSH opens an interactive shell you don't need. - **`-f`**: Fork to the background after authentication. Without this, the tunnel blocks your terminal. For interactive exploration (testing), omit `-f` so you can see the output. For production use, always include both. ### Local port forwarding Forward a local port to a service on a remote machine: ```bash ssh -f -N -L [local_port]:[remote_host]:[remote_port] user@remote-server ``` - `[local_port]` — Port on your local machine (e.g., 3306). - `[remote_host]` — Address of the remote host (usually `127.0.0.1` if the service runs on the remote server itself). - `[remote_port]` — Port of the service on the remote host. - `user@remote-server` — SSH user and remote server address. **Example** — Forward remote MySQL (port 3306) to your local machine: ```bash ssh -f -N -L 3306:127.0.0.1:3306 user@remote-server ``` **Verify the tunnel is working:** ```bash # Confirm the port is listening locally ss -tuln | grep 3306 # Test the connection mysql -h 127.0.0.1 -P 3306 -u username -p ``` ### Remote port forwarding Expose a local service to a remote server: ```bash ssh -f -N -R [remote_port]:[local_host]:[local_port] user@remote-server ``` - `[remote_port]` — Port on the remote server (e.g., 8080). - `[local_host]` — Address of your local host (usually `127.0.0.1`). - `[local_port]` — Port of the service on your local machine (e.g., 80 for a web server). **Example** — Expose a local web server (port 80) on the remote server at port 8080: ```bash ssh -f -N -R 8080:127.0.0.1:80 user@remote-server ``` **Verify** — On the remote server: ```bash ss -tuln | grep 8080 curl http://localhost:8080 ``` For the forwarded port to be accessible from outside the remote server (not just localhost), the SSH server needs `GatewayPorts` configured. See the [SSH Tunnel Security Best Practices](#ssh-tunnel-security-best-practices) section for the safe way to set this up. ### Dynamic port forwarding (SOCKS proxy) Set up a SOCKS proxy on your local machine: ```bash ssh -f -N -D [local_port] user@remote-server ``` - `[local_port]` — Port on your local machine for the SOCKS proxy (e.g., 1080). **Example:** ```bash ssh -f -N -D 1080 user@remote-server ``` **Verify** — Configure your browser to use SOCKS5 proxy at `127.0.0.1:1080`, then visit `https://ifconfig.me` to confirm your traffic routes through the remote server. ## Using ~/.ssh/config for reusable tunnels Typing long SSH commands every time gets old fast. Define your tunnels in `~/.ssh/config` and start them with a single short command. ```ssh-config # ~/.ssh/config Host db-tunnel HostName remote-server.example.com User deploy LocalForward 5432 127.0.0.1:5432 ServerAliveInterval 60 ServerAliveCountMax 3 ExitOnForwardFailure yes IdentityFile ~/.ssh/id_ed25519 ``` Start the tunnel: ```bash ssh -f -N db-tunnel ``` Now `localhost:5432` connects to the remote PostgreSQL server. ```ssh-config # ~/.ssh/config Host expose-local-app HostName public-vps.example.com User deploy RemoteForward 8080 127.0.0.1:3000 ServerAliveInterval 60 ServerAliveCountMax 3 ExitOnForwardFailure yes ``` Start the tunnel: ```bash ssh -f -N expose-local-app ``` Your local app on port 3000 is now accessible at `public-vps.example.com:8080`. ```ssh-config # ~/.ssh/config Host vpn-tunnel HostName vps.example.com User deploy DynamicForward 1080 ServerAliveInterval 60 ServerAliveCountMax 3 ExitOnForwardFailure yes ``` Start the tunnel: ```bash ssh -f -N vpn-tunnel ``` Configure your browser with SOCKS5 proxy `127.0.0.1:1080`. **Verify your config resolves correctly:** ```bash ssh -G db-tunnel ``` This dumps the resolved configuration — check that `localforward`, `hostname`, and `user` are correct. ## Persistent SSH tunnels Tunnels die silently when NAT or firewall timeouts drop idle TCP connections. This is the number-one operational pain point with SSH tunnels. Here's how to make them survive. ### Keeping tunnels alive with ServerAliveInterval The client-side directive `ServerAliveInterval` sends keepalive packets at regular intervals to prevent idle connection timeouts. **Recommended values in `~/.ssh/config`:** ```ssh-config ServerAliveInterval 60 ServerAliveCountMax 3 ``` This sends a keepalive every 60 seconds. If three consecutive keepalives go unanswered (180 seconds total), SSH closes the connection. You can also pass these as flags: ```bash ssh -o ServerAliveInterval=60 -o ServerAliveCountMax=3 -f -N -L 5432:127.0.0.1:5432 user@host ``` These are easy to mix up: - **`ServerAliveInterval`**: Client-side. The **client** asks the server "are you alive?" This is what you want for tunnels. Goes in `~/.ssh/config` or as an `-o` flag. - **`ClientAliveInterval`**: Server-side. The **server** asks the client "are you alive?" Goes in `/etc/ssh/sshd_config`. The original article showed this as a client option, which was incorrect. For keeping SSH tunnels alive, use `ServerAliveInterval` on the client. ### ExitOnForwardFailure: don't silently fail If a port forward fails to bind (port already in use, permission denied), SSH connects anyway **without the tunnel**. You think it's working, but traffic isn't being forwarded. `ExitOnForwardFailure yes` makes SSH exit with an error instead of silently connecting without the tunnel. ```bash ssh -o ExitOnForwardFailure=yes -f -N -L 8080:localhost:80 user@host ``` Or in `~/.ssh/config`: ```ssh-config Host my-tunnel HostName host.example.com ExitOnForwardFailure yes LocalForward 8080 localhost:80 ``` Always include this. It prevents the most common silent failure mode with SSH tunnels. ### Running SSH tunnels as systemd services This is the boring-reliable way to keep a tunnel alive across reboots. No need for `autossh` — systemd's `Restart=always` handles restarts, and `ServerAliveInterval` handles dead connection detection. **Create the service file:** ```ini # /etc/systemd/system/ssh-tunnel-db.service [Unit] Description=SSH Tunnel to production database After=network-online.target Wants=network-online.target [Service] Type=simple User=deploy ExecStart=/usr/bin/ssh -N -o ExitOnForwardFailure=yes \ -o ServerAliveInterval=60 -o ServerAliveCountMax=3 \ -L 5432:127.0.0.1:5432 tunnel-user@db-host.example.com Restart=always RestartSec=15 [Install] WantedBy=multi-user.target ``` **Enable and start:** ```bash sudo systemctl daemon-reload sudo systemctl enable --now ssh-tunnel-db ``` **Verify:** ```bash systemctl status ssh-tunnel-db ss -tuln | grep 5432 ``` systemd's `Restart=always` combined with `ServerAliveInterval` handles reconnection. When SSH detects a dead connection (three missed keepalives), it exits. systemd restarts the service after 15 seconds. `autossh` still works but is often unnecessary on modern systems. **Common failure mode:** The service user needs access to the SSH key. If the tunnel fails to start, check: ```bash sudo journalctl -u ssh-tunnel-db -n 20 ``` Make sure the key file has correct permissions: ```bash sudo chmod 600 /home/deploy/.ssh/id_ed25519 sudo chown deploy:deploy /home/deploy/.ssh/id_ed25519 ``` ## Tunneling through jump hosts (ProxyJump) A common setup: your database lives on a private server that's only accessible through a bastion/jump host. SSH can chain through the bastion with the `-J` flag (requires OpenSSH 7.3+, available on Ubuntu 18.04+, Debian 10+, and all current distros). **Command:** ```bash ssh -J jump-user@bastion.example.com \ -f -N \ -L 5432:127.0.0.1:5432 \ db-user@private-db.internal ``` This connects to the bastion first, then opens a tunnel through it to the private database server. **In `~/.ssh/config`:** ```ssh-config Host db-via-bastion HostName private-db.internal User db-user ProxyJump jump-user@bastion.example.com LocalForward 5432 127.0.0.1:5432 ServerAliveInterval 60 ExitOnForwardFailure yes ``` Then just: ```bash ssh -f -N db-via-bastion ``` `-J` (ProxyJump) is the modern approach. The older `ProxyCommand ssh jump-host nc %h %h` pattern still works but is harder to configure and less efficient. If you're on OpenSSH 7.3+, use `-J`. For a deeper dive, see our guide on [SSH ProxyJump and jump hosts](/ssh-proxyjump-jumphost/). ## SSH tunnel security best practices Tunnels forward traffic by design, which means misconfigured forwarding can expose private services to the internet. Here's how to lock things down. ### GatewayPorts: no vs clientspecified vs yes The `GatewayPorts` directive in `/etc/ssh/sshd_config` controls whether remote port forwards are accessible from outside the server. ```ssh-config # In /etc/ssh/sshd_config on the remote server: # GatewayPorts no # default: forwarded ports only on localhost (safest) # GatewayPorts clientspecified # client chooses the bind address per connection # GatewayPorts yes # ⚠️ binds to ALL interfaces (0.0.0.0) ``` | Value | Behavior | When to use | |-------|----------|-------------| | `no` (default) | Forwarded ports only accessible from localhost on the remote server | Most cases — this is safe | | `clientspecified` | Client decides the bind address per connection | **Recommended** when you need external access selectively | | `yes` | Always binds to all interfaces (0.0.0.0) | Trusted networks only — never on a public VPS | On a public VPS, `GatewayPorts yes` binds forwarded ports to 0.0.0.0, making them accessible from anywhere on the internet. Use `clientspecified` instead, and bind to specific interfaces in your SSH command when needed. After changing this, restart the SSH daemon: ```bash sudo systemctl restart sshd ``` ### SSH key authentication Always use SSH key pairs over passwords. Generate an Ed25519 key: ```bash ssh-keygen -t ed25519 -C "your-comment" ``` Copy the public key to the remote server: ```bash ssh-copy-id user@remote-server ``` Disable password authentication in `/etc/ssh/sshd_config` on the server: ```ssh-config PasswordAuthentication no PubkeyAuthentication yes ``` ### Restricting forwarding with PermitOpen and PermitListen For dedicated tunnel accounts, restrict which ports can be forwarded: ```ssh-config # In /etc/ssh/sshd_config Match User tunnel-user PermitOpen 127.0.0.1:5432 PermitListen 127.0.0.1:8080 AllowTcpForwarding yes ``` - `PermitOpen` limits which hosts/ports the user can forward traffic **to** (for `-L`). - `PermitListen` limits which hosts/ports the user can listen **on** (for `-R`). Available since OpenSSH 7.8. This is critical when you create a user account specifically for database tunnels. ### AllowTcpForwarding granularity The default `AllowTcpForwarding yes` (or `all`) allows both local and remote forwarding. You can restrict it: | Value | Allowed | |-------|---------| | `yes` / `all` | Both `-L` and `-R` | | `local` | Only `-L` (local forwarding) | | `remote` | Only `-R` (remote forwarding) | | `no` | Neither | Available since OpenSSH 6.2. ### Creating a tunnel-only user with Match blocks For production database tunnels, create a user that can only forward ports — no shell access: ```ssh-config # In /etc/ssh/sshd_config Match User tunnel-only AllowTcpForwarding remote PermitListen 127.0.0.1:8080 PermitOpen 127.0.0.1:5432 ForceCommand /bin/false X11Forwarding no PermitTunnel no ``` This user can set up remote forwards on port 8080 and open tunnels to 127.0.0.1:5432, and nothing else. Even if the SSH key is compromised, the blast radius is limited. For broader server hardening, see [securing a VPS with CrowdSec](/crowdsec-secure-server/). ### Firewalls Keep a properly configured firewall on both local and remote machines: ```bash sudo ufw enable sudo ufw allow ssh ``` If you're running Docker on the remote server, be aware that [Docker bypasses your firewall](/docker-bypasses-firewall/) by inserting its own iptables rules. A port exposed via Docker Compose is open to the internet regardless of UFW rules. See [securing a Docker server with UFW](/bsi-security-report-docker-ufw/) for the fix. ## Troubleshooting SSH tunnels ### Verify the tunnel is listening ```bash # Replace 5432 with your port ss -tuln | grep 5432 ``` Expected output — a line showing `LISTEN` on `127.0.0.1:5432`. ### Test connectivity ```bash curl -v http://localhost:8080 # or for non-HTTP services: telnet localhost 5432 ``` For checking remote ports specifically, see [checking remote ports with nc](/check-remote-port-in-linux-nc/). ### Debug with verbose logging Add `-v` for basic debug output, `-vvv` for maximum verbosity: ```bash ssh -v -N -L 8080:localhost:80 user@host ``` This shows the SSH handshake, authentication details, and forwarding setup. If the tunnel fails to bind, you'll see the error here. ### Check SSH logs ```bash # On the server sudo journalctl -u ssh -f # or sudo tail -f /var/log/auth.log ``` ### Common failure modes | Symptom | Cause | Fix | |---------|-------|-----| | `bind: Address already in use` | Port is in use | `ss -tuln \| grep `, kill the process or pick another port | | `Permission denied` on low ports (<1024) | Non-root user | Use a port >1024 or set up an iptables redirect | | Tunnel connects but port not listening | Missing `-N` or forward failed silently | Add `ExitOnForwardFailure yes` | | Tunnel dies after idle minutes | NAT/firewall timeout | Add `ServerAliveInterval 60` | | `Connection refused` from remote | Firewall blocking, or `AllowTcpForwarding no` | Check `sshd_config`, check `ufw status` | | `Warning: remote port forwarding failed` | `GatewayPorts` not configured, or port in use on remote | Check `GatewayPorts` in sshd_config, check port on remote | Find the tunnel process: ```bash ps aux | grep 'ssh -f -N' ``` Kill it by PID: ```bash kill ``` Or kill all matching tunnels at once: ```bash pkill -f 'ssh -f -N -L 5432' ``` If the tunnel is running as a systemd service, stop it with: ```bash sudo systemctl stop ssh-tunnel-db ``` Without `PermitOpen` and `PermitListen`, a user with SSH access can forward **any** port to **any** host reachable from the server. If an attacker compromises the tunnel user's SSH key, they could reach internal services, databases, or management interfaces. Restricting these directives limits the blast radius — the compromised key only grants access to the specific ports you've explicitly allowed. This is defense-in-depth: even if the key leaks, the damage is contained. ## Conclusion SSH port forwarding is a core tool for any Linux operator. The three types (local, remote, and dynamic) cover most network access scenarios without exposing extra ports publicly. What this guide covered: - The three types of SSH port forwarding and when to use each. - Practical commands with `-f -N` flags for tunnel-only sessions. - Reusable `~/.ssh/config` definitions so you don't retype commands. - Persistent tunnels using systemd services and `ServerAliveInterval`, no `autossh` needed. - Jump host chaining with ProxyJump for bastion-based access patterns. - Security hardening: `GatewayPorts` nuance, `PermitOpen`/`PermitListen` restrictions, and tunnel-only users. - Troubleshooting: verify commands, verbose logging, and common failure modes. SSH tunnels are the quick-access tool in your networking kit. For permanent service exposure, look at dedicated reverse proxies or mesh VPNs. Start with the basics, get a tunnel working, verify it with `ss` and `curl`, then harden it with the security practices above. > **Looking for more tunneling options?** SSH tunnels are great for quick access, but if you need persistent tunnels for exposing services, check out [Pangolin](/pangolin-cloudflare-tunnels-alternative/) (self-hosted tunnel alternative) or our [mesh VPN comparison](/netbird-vs-headscale-vs-tailscale/) for connecting entire networks with WireGuard. If you want to self-host your own Tailscale-compatible network, see [Headscale](/headscale-self-hosted-tailscale-setup/).

How to Fix Docker Bypassing Firewall: A Complete Guide

Mon, 10 Aug 2026 00:00:00 GMT

import Notice from "@components/widgets/Notice.astro"; import ListCheck from "@components/widgets/ListCheck.astro"; If you're [managing your own servers](https://www.bitdoze.com/secure-ssh-server-linux/) and running Docker containers, there's a security issue you need to know about: Docker bypasses your system's firewall by default. It's not a bug, it's how Docker's networking works. But it means the UFW or iptables rules you set up are not protecting your containers the way you'd expect. This guide covers every practical fix, from the two-minute localhost binding to architectural changes like rootless Docker. Everything here is tested with Docker 28.x and 29.x. Docker's networking changed substantially in 28.0.0 (Feb 2025) and 29.0.0 (Nov 2025). The iptables chain structure was reworked, and nftables support arrived as experimental. If you're on 27.x or older, the iptables commands below will still work, but the internal chain layout differs. ## Understanding the problem: why Docker bypasses the firewall Docker creates its own bridge network (usually `docker0`) and manages container networking through iptables (or nftables on newer setups). When you run a container with a port mapping like this: ```yaml services: myapp: image: nginx ports: - "8080:80" ``` You might think you're opening port 8080 on localhost only. What actually happens: Docker binds to `0.0.0.0:8080` and inserts DNAT rules into your iptables, ahead of your regular firewall rules. So your UFW rules saying "block everything except 22, 80, 443" don't apply to Docker's forwarded traffic. If you're [setting up containers for your home server](https://www.bitdoze.com/docker-containers-home-server/) or a VPS, this can expose services you thought were internal. You can see Docker's rules in action: ```bash sudo iptables -L -n -v | grep DOCKER ``` You'll see rules Docker added automatically. These are what bypass your firewall. This is by design. Docker needs network control for inter-container communication and published ports. But "by design" doesn't mean "acceptable for your setup." Here's how to fix it. After a firewalld reload, published container ports could be accessed directly from the local network, even when bound to loopback. If you're running Docker 28.0 through 28.3.2, update immediately. This was fixed in 28.3.3. > If you are interested to see some free cool open source self hosted apps you can check [toolhunt.net self hosted section](https://toolhunt.net/sh/). ## Solutions: configuring the firewall to control Docker traffic These solutions range from quick fixes to architectural changes. Start with the first one and work down as needed. ### 1. Using localhost binding (the simplest fix) The fastest mitigation: bind containers to `127.0.0.1` so they're only accessible from the host itself. ```yaml services: myapp: image: nginx ports: - "127.0.0.1:8080:80" ``` This works because Docker skips its DNAT chain for loopback-bound ports. The container is reachable from localhost but invisible to the outside world. **Limitations**: Other hosts on the same network can't reach the container directly. For external access, you need a reverse proxy (Traefik, Caddy, Nginx) in front. That's the recommended pattern anyway. ### 2. Using a Cloud firewall Cloud-level firewalls operate at the network layer, before traffic ever hits your VPS. Docker can't touch them because they run outside the host. Providers with network-level firewalls: - **AWS Security Groups**: instance-level inbound/outbound rules - **[Hetzner Cloud Firewalls](https://go.bitdoze.com/hetzner)**: network-level filtering, free, easy to configure - **[DigitalOcean Cloud Firewalls](https://go.bitdoze.com/do)**: similar to security groups - **Google Cloud Firewall Rules**: tag-based network filtering These can't be bypassed by Docker's iptables manipulation. My typical setup: 1. Allow ports 80, 443 (web traffic) and 22 (SSH) 2. Block all other incoming traffic 3. Add specific rules for any additional services This is your outermost defense layer. It doesn't replace fixing Docker's behavior on the host, but it catches anything that slips through. ### 3. Using Traefik as a reverse proxy Using [Traefik as a reverse proxy](https://www.bitdoze.com/traefik-proxy-docker/) is one of the best long-term solutions. Only Traefik's ports are exposed. Everything else stays hidden. Only Traefik's ports are exposed. All other containers remain hidden behind it. Built-in Let's Encrypt, rate limiting, and middleware. No need to manage TLS certs per container. Here's a working setup: ```yaml services: traefik: image: traefik:v3 command: - "--providers.docker=true" - "--api.dashboard=true" - "--certificatesresolvers.letsencrypt.acme.tlschallenge=true" - "--certificatesresolvers.letsencrypt.acme.email=your@email.com" - "--entrypoints.web.address=:80" - "--entrypoints.websecure.address=:443" - "--entrypoints.web.http.redirections.entrypoint.to=websecure" ports: - "80:80" - "443:443" volumes: - /var/run/docker.sock:/var/run/docker.sock:ro - letsencrypt:/letsencrypt labels: - "traefik.enable=true" myapp: image: nginx labels: - "traefik.enable=true" - "traefik.http.routers.myapp.rule=Host(`your-domain.com`)" - "traefik.http.routers.myapp.entrypoints=websecure" - "traefik.http.routers.myapp.tls.certresolver=letsencrypt" # Notice: no ports exposed directly volumes: letsencrypt: ``` For the Traefik dashboard, secure it with basic authentication. The placeholder hash `$$apr1$$xyz123$$` won't work. Generate a real one: ```bash echo $(htpasswd -nbB admin 'your-password') | sed -e 's/\$/\$\$/g' ``` Add the result to your Traefik labels or a file provider. For a full walkthrough on [securing the proxy itself with basic authentication](https://www.bitdoze.com/traefik-basic-authentication/), see that dedicated guide. ### 4. Using Caddy + caddy-docker-proxy (lightweight alternative) If Traefik feels like overkill, [Caddy](https://caddyserver.com/) with the `lucaslorentz/caddy-docker-proxy` plugin gives you automatic HTTPS with simpler config: ```yaml services: caddy: image: lucaslorentz/caddy-docker-proxy:ci-alpine ports: - "80:80" - "443:443" volumes: - /var/run/docker.sock:/var/run/docker.sock:ro - caddy_data:/data environment: - CADDY_INGRESS_NETWORK=caddy myapp: image: nginx labels: caddy: your-domain.com caddy.reverse_proxy: "{{upstreams 80}}" # No ports exposed directly networks: default: name: caddy external: true volumes: caddy_data: ``` Create the external network first: `docker network create caddy`. **Caddy vs Traefik**: Caddy has a simpler config model and automatic HTTPS by default (no explicit certresolver config). Traefik has more middleware options, a richer dashboard, and better support for complex routing. For solo operators running a handful of services, Caddy is often the better fit. ### 5. Using ufw-docker: the simplest UFW + Docker fix If you're using UFW, this is the tool you probably didn't know existed. [chaifeng/ufw-docker](https://github.com/chaifeng/ufw-docker) (6.6k+ stars on GitHub) automates the fix for Docker bypassing UFW. ufw-docker is the de facto community solution for UFW + Docker. It replaces manual after.rules editing with simple per-container commands. **Install:** ```bash sudo wget -O /usr/local/bin/ufw-docker \ https://github.com/chaifeng/ufw-docker/raw/master/ufw-docker sudo chmod +x /usr/local/bin/ufw-docker sudo ufw-docker install ``` The `install` command modifies `/etc/ufw/after.rules` (and `after6.rules` for IPv6) to add Docker-aware filtering rules. It backs up the existing file first. **Allow a container's port through the firewall:** ```bash sudo ufw-docker allow myapp 80 sudo ufw-docker allow myapp 443/tcp ``` **List rules for a container:** ```bash sudo ufw-docker list myapp ``` **Remove a rule:** ```bash sudo ufw-docker delete allow myapp 80 ``` **Key advantage over manual rules**: `ufw-docker` keeps `DEFAULT_FORWARD_POLICY="DROP"` (the safe default) and only opens what you explicitly allow. The manual approach of setting it to `ACCEPT` opens all forwarded traffic. That's a broad hammer. I documented my full experience [securing a Docker server after a BSI security report](https://www.bitdoze.com/bsi-security-report-docker-ufw/) if you want the complete story. ## Advanced firewall configurations: working with iptables and UFW If you need finer-grained control or you're not using UFW, these approaches work at the iptables level. ### Working with iptables and the DOCKER-USER chain The `DOCKER-USER` chain is special: Docker intentionally does not modify rules you put there. It's processed before Docker's own forwarding rules, so it's the right place for admin-defined filtering. In Docker 28.2.2 (May 2025), Docker stopped adding an explicit RETURN rule to DOCKER-USER. This means you can now both append (-A) and insert (-I) rules. If you previously relied on the implicit RETURN, verify your rule order still works after upgrading. Here's the standard pattern: ```bash # Allow established connections (don't break existing traffic) sudo iptables -A DOCKER-USER -i eth0 -j ACCEPT -m conntrack --ctstate ESTABLISHED,RELATED # Allow traffic from a specific IP sudo iptables -A DOCKER-USER -i eth0 -s 203.0.113.1 -j ACCEPT # Allow traffic from a trusted subnet sudo iptables -A DOCKER-USER -i eth0 -s 10.0.0.0/8 -j ACCEPT # Drop everything else coming from eth0 to containers sudo iptables -A DOCKER-USER -i eth0 -j DROP ``` Replace `eth0` with your actual public interface (check with `ip a`). **Make rules persistent across reboots:** ```bash sudo apt install iptables-persistent sudo netfilter-persistent save sudo netfilter-persistent reload ``` Without `iptables-persistent`, your rules vanish on reboot. **Verify your rules:** ```bash sudo iptables -L DOCKER-USER -n -v --line-numbers ``` You should see your rules listed with packet counters. If counters stay at zero, the rules aren't matching. Check the interface name. ### Working with firewalld firewalld uses zones to represent different network environments. You can create a dedicated zone for Docker interfaces: **1. Create a zone for Docker:** ```bash sudo firewall-cmd --permanent --new-zone=docker ``` **2. Bind Docker interfaces to the zone:** ```bash # Default docker0 bridge sudo firewall-cmd --permanent --zone=docker --add-interface=docker0 # User-defined networks (replace br-xxx with actual interface) # Find the interface name: docker network ls docker network inspect | grep "Interface" sudo firewall-cmd --permanent --zone=docker --add-interface=br-xxxxx ``` **3. Define rules in the Docker zone:** ```bash sudo firewall-cmd --permanent --zone=docker --add-port=8080/tcp sudo firewall-cmd --permanent --zone=docker --add-service=http ``` **4. Apply and verify:** ```bash sudo firewall-cmd --reload sudo firewall-cmd --zone=docker --list-all ``` ### Using UFW (Uncomplicated Firewall): manual approach If you prefer manual control over `ufw-docker`, here's the traditional approach. **1. Set the forward policy** in `/etc/default/ufw`: ```bash DEFAULT_FORWARD_POLICY="ACCEPT" ``` Setting DEFAULT_FORWARD_POLICY to ACCEPT opens all forwarded traffic. The ufw-docker tool (covered above) keeps this at DROP and only opens what you explicitly allow. Use ufw-docker unless you have a specific reason to manage the rules manually. **2. Add Docker-specific rules** to `/etc/ufw/after.rules` (append before the final `COMMIT`): ```bash # NAT table rules *nat :POSTROUTING ACCEPT [0:0] # Forward traffic through eth0 -A POSTROUTING -s 172.17.0.0/16 ! -o docker0 -j MASQUERADE COMMIT # Don't delete these required lines *filter :ufw-user-forward - [0:0] :ufw-docker-logging-deny - [0:0] :DOCKER-USER - [0:0] # Allow Docker internal traffic -A DOCKER-USER -j RETURN -s 10.0.0.0/8 -A DOCKER-USER -j RETURN -s 172.16.0.0/12 -A DOCKER-USER -j RETURN -s 192.168.0.0/16 -A DOCKER-USER -j ufw-user-forward -A DOCKER-USER -j DROP COMMIT ``` **3. Apply:** ```bash sudo ufw reload ``` ### Rootless Docker: the aggressive option Rootless Docker runs the daemon as a non-root user. Because it can't manipulate iptables directly, published ports are forwarded via userland networking (`slirp4netns` or `gvisor-tap-vsock`), and host firewall rules are respected. This effectively eliminates the bypass problem. Trade-offs: - No `--net=host` mode - Some features unavailable (AppArmor, certain storage drivers) - Slightly different networking behavior - Requires per-user setup with `dockerd-rootless-setuptool.sh` Rootless Docker solves the firewall bypass but introduces operational complexity. Not all images work cleanly under rootless mode, and debugging networking issues is harder. Consider this for single-user VPS setups, not shared servers. If you're evaluating container runtimes, [Podman handles firewall rules differently](https://www.bitdoze.com/podman-vs-docker/) and may be worth considering as an alternative. ## Docker network isolation and best practices Firewall rules are one layer. Network isolation is another. Use both. ### Using Docker Compose networks Custom networks let you control which containers can talk to each other: - **Internal networks** (`internal: true`): completely isolated. Containers can't reach the internet or external services. Perfect for databases. - **External networks** (`internal: false`): containers can reach the internet and be reached from outside. Needs firewall rules. Here's how I organize containers with network isolation: ```yaml networks: frontend: internal: false # Allows external access backend: internal: true # Completely isolated from external access services: web: image: nginx networks: - frontend ports: - "127.0.0.1:8080:80" security_opt: - no-new-privileges:true api: image: node networks: - frontend - backend depends_on: - database database: image: mysql networks: - backend # Only connected to internal network environment: MYSQL_ROOT_PASSWORD_FILE: /run/secrets/db_root_password secrets: - db_root_password security_opt: - no-new-privileges:true secrets: db_root_password: file: ./secrets/db_password.txt ``` This ensures the database is completely isolated from external access, the API bridges both networks, and all external entry goes through localhost. For more on [Docker Compose secrets](https://www.bitdoze.com/docker-compose-secrets/) and what actually works for secret management, see that dedicated guide. You can also define explicit subnets for tighter control: ```yaml networks: frontend: internal: false ipam: config: - subnet: 172.20.0.0/24 backend: internal: true ipam: config: - subnet: 172.20.1.0/24 ``` **Audit your networks regularly:** ```bash docker network ls docker network inspect frontend docker stats --format "table {{.Name}}\t{{.NetIO}}" docker network prune # Remove unused networks ``` ### Container resource limits The `deploy.resources.limits` syntax in docker-compose.yml is only honored by Docker Swarm (docker stack deploy). For standalone `docker compose`, use the top-level service keys shown below. **For standalone `docker compose`:** ```yaml services: web: image: nginx cpu_count: 1 cpu_percent: 50 mem_limit: 512m memswap_limit: 512m # Prevent swap abuse ``` **For Docker Swarm (`docker stack deploy`):** ```yaml services: web: image: nginx deploy: resources: limits: cpus: '0.50' memory: 512M reservations: cpus: '0.25' memory: 256M ``` ### Docker 28+ gateway modes Docker 28.0.0 introduced bridge network gateway modes for finer-grained control over how container ports are exposed on the host: - `nat-unprotected`: NAT is applied but no per-port iptables rules are created. Useful for when you want NAT but manage port access through DOCKER-USER. - `isolated`: No bridge IP on the host. The host can't reach containers directly. - `routed`: Containers are accessible from other bridge networks via routing. Create a network with a specific mode: ```bash docker network create --opt com.docker.network.bridge.gateway_mode=nat-unprotected mynet ``` This is for advanced operators. If the default behavior plus a reverse proxy solves your problem, you don't need to touch gateway modes. ### nftables backend: the future (Docker 29+) nftables support is experimental. Use for testing and evaluation. The iptables backend remains the default and is fully supported. There is no DOCKER-USER chain equivalent with nftables yet. Filtering is done via nftables sets and rules. Docker 29.0.0 (Nov 2025) introduced experimental nftables support. Instead of iptables, Docker manages firewall rules through nftables: ```json // /etc/docker/daemon.json { "firewall-backend": "nftables" } ``` With the nftables backend, you must enable IP forwarding manually (Docker doesn't do it automatically as with iptables): ```bash echo 'net.ipv4.ip_forward=1' | sudo tee /etc/sysctl.d/99-docker.conf sudo sysctl --system sudo systemctl restart docker ``` Key differences from the iptables backend: - No DOCKER-USER chain. Use nftables rules directly. - Not yet supported in Swarm mode. - Requires kernel with nftables support (all modern distros have this). This will eventually become the default. For now, stick with iptables unless you're testing. ## Verifying your firewall configuration After applying any of the fixes above, verify that it actually works. Don't assume.

Check what's actually exposed: docker ps --format "table {'{'}{'{'} .Names {'}'}{'}'}\t{'{'}{'{'} .Ports {'}'}{'}'}", verify no unexpected 0.0.0.0 bindings
Test from outside: nc -zv <public-ip> <port> from a different host. Confirm a port is blocked when it should be
Inspect iptables rules: iptables -L DOCKER-USER -n -v --line-numbers. Verify your rules are in the right order
Trace NAT rules: iptables -t nat -L -n -v. See Docker's DNAT rules and where they sit relative to your firewall
Check UFW status: ufw status verbose. Confirm rules are active and correct
Audit all networks: docker network ls and docker network inspect <name>

Here are the concrete commands: ```bash # 1. See exactly what ports are exposed and where docker ps --format "table {{.Names}}\t{{.Ports}}" # 2. Test a port from an external host (run on a different machine) nc -zv YOUR_PUBLIC_IP 8080 # 3. Check DOCKER-USER chain rules and packet counts sudo iptables -L DOCKER-USER -n -v --line-numbers # 4. Inspect all NAT rules (look for DNAT entries from Docker) sudo iptables -t nat -L -n -v # 5. UFW status sudo ufw status verbose # 6. List and inspect networks docker network ls docker network inspect bridge ``` If `nc` succeeds on a port you expected to be blocked, your fix didn't apply. Recheck the interface name in your iptables rules (`eth0` vs `ens3` vs `enp0s3`, it varies by distro and cloud provider). ## Conclusion: keeping your Docker containers secure Docker bypasses host firewalls by default. That's the reality. But it's manageable with a layered approach: 1. **Localhost binding + reverse proxy** as the foundation. Bind containers to `127.0.0.1`, expose only Traefik or Caddy to the public. This single pattern eliminates most of the risk. 2. **Host firewall** with `ufw-docker` (for UFW users) or DOCKER-USER iptables rules (for iptables users). Control exactly which container ports are reachable and from where. 3. **Cloud firewall** as the outer layer. Network-level filtering that Docker can't touch. 4. **Docker network isolation** for defense in depth. Internal networks for databases and backend services. Keep Docker updated. CVE-2025-54388 showed that even loopback-bound ports could be exposed after a firewalld reload on affected versions. If you're running security-critical containers, staying current isn't optional. For layering security beyond Docker itself, consider [CrowdSec](https://www.bitdoze.com/crowdsec-secure-server/) for automated intrusion detection and response.

Bind all containers to 127.0.0.1 unless they must be publicly accessible
Deploy a reverse proxy (Traefik or Caddy) for all public services
Install ufw-docker or configure DOCKER-USER iptables rules
Set up a cloud firewall allowing only ports 22, 80, 443
Use internal networks for databases and backend services
Verify with nc -zv from an external host after every change
Keep Docker updated. Check release notes before upgrading
Regularly [clean up unused Docker resources](https://www.bitdoze.com/clean-docker-overlay2-dir/) to reduce attack surface

Security isn't about implementing every possible measure. It's about the right combination for your situation. For most solo operators running Docker on a VPS: localhost binding + reverse proxy + `ufw-docker` + cloud firewall covers the vast majority of exposure. The rest is network isolation and keeping things updated. If you're getting started with Docker, check out the [essential Docker commands](https://www.bitdoze.com/docker-commands/) and how to [copy multiple files efficiently in Dockerfiles](https://www.bitdoze.com/copy-multiple-files-in-one-layer-using-a-dockerfile/).

How To Access Remote Servers with SSH ProxyJump and Jump Hosts

Mon, 10 Aug 2026 00:00:00 GMT

import Button from "@components/widgets/Button.astro"; import Notice from "@components/widgets/Notice.astro"; import ListCheck from "@components/widgets/ListCheck.astro"; Accessing servers tucked away in a private network shouldn't require a VPN appliance, a browser plugin, or three hours of firewall debugging. SSH jump hosts and the built-in ProxyJump feature solve this with one command and zero extra software. A jump host is a single, hardened server exposed to the internet that acts as a relay to your internal machines. Instead of leaving every server reachable from the public internet (which is like leaving all your doors unlocked), you lock everything behind one well-guarded entrance. ProxyJump, built into OpenSSH since version 7.3, turns that two-step login into a single transparent connection. Before using jump hosts, I was relying on [basic SSH security measures](https://www.bitdoze.com/secure-ssh-server-linux/), which were not enough once servers span multiple private networks. This guide covers the full picture: how jump hosts work, how to configure ProxyJump with SSH config files, port forwarding and multiplexing through jump hosts, security hardening for bastion servers, and troubleshooting the failures you'll actually hit. ![Benefits of using SSH jump hosts and ProxyJump for secure server access](../../assets/images/25/01/benefits-jumphosts.png) ## Prerequisites Before you start, make sure you have the following:

A VPS or dedicated server to act as your jump host (1 vCPU, 512 MB RAM, 10 GB disk is enough, SSH traffic bandwidth is negligible)
OpenSSH 7.3+ on your client machine (for ProxyJump support; most modern distros qualify)
SSH key pair generated (ed25519 recommended: `ssh-keygen -t ed25519`)
Comfortable with basic Linux commands
Root or sudo access on the jump host to edit sshd_config and firewall rules

Run `ssh -V` on your client. Anything from 7.3 (2016) onwards supports ProxyJump. Ubuntu 24.04 ships 9.6p1, Debian 12 ships 9.2p1, both are fine. On the server side, OpenSSH 9.8+ gives you built-in abuse protection (PerSourcePenalties), which is covered later in this guide. A jump host needs almost no resources. A [Hetzner CX22](https://go.bitdoze.com/hetzner) at ~€4/month is more than enough. [Hostinger VPS](https://go.bitdoze.com/hostinger-vps) and [Vultr](https://go.bitdoze.com/vultr) are alternatives if you need a different region or billing model. ## Understanding the basics: what is SSH? SSH (Secure Shell) is an encrypted protocol for running commands on a remote machine as if you were sitting in front of it. Every keystroke travels through an encrypted tunnel — nobody on the wire can read it. Basic usage: ```bash ssh username@remote-server # For example: ssh john@192.168.1.100 ``` The connection follows a client-server model: your machine initiates, the remote machine authenticates, and from that point you have a shell. If you're new to server management, check out how to [secure your SSH server](https://www.bitdoze.com/secure-ssh-server-linux/) before exposing anything to the internet. The straightforward connection works fine when the target has a public IP and you can reach port 22. What about servers in private subnets with no public address? That's where jump hosts come in. ## What is a jump host (or bastion host)? A jump host (also called a bastion host) is a dedicated server that acts as the single gateway to your internal network. Think of it as the secure lobby in a building: everyone checks in through one well-guarded entrance instead of wandering in through random doors. Here's a typical setup: ``` Internet -> Jump Host -> Internal Servers (Public) (Public) (Private) ``` ![Typical SSH jump host setup showing Internet, Jump Host, and Internal Servers flow](../../assets/images/25/01/jumphost1.png) To reach an internal server through a jump host manually, you'd do: ```bash # First, connect to the jump host ssh jumpuser@jump-host.example.com # Then, from the jump host, connect to the internal server ssh internaluser@internal-server ``` This two-step process works, but it's clunky. You have to manage credentials on the jump host, sessions are nested, and file transfers require extra hops. The main reasons to use a jump host despite the friction: 1. **Single exposure point**: only the jump host has a public IP, reducing your attack surface to one machine 2. **Centralized access control**: all connections flow through one place, making it easier to grant and revoke access 3. **Audit trail**: you can track who connected to what and when, all from one log 4. **Simplified firewall rules**: only the jump host needs SSH open to the internet ## Introducing SSH ProxyJump: a simpler way to use jump hosts ProxyJump was introduced in OpenSSH 7.3 (2016) and it eliminated the two-step dance. Instead of manually connecting to the jump host and then to your target, you do it all in one command: ```bash # Old way (two separate connections): ssh jumpuser@jumphost ssh internaluser@internal-server # With ProxyJump (one command): ssh -J jumpuser@jumphost internaluser@internal-server ``` The `-J` flag tells SSH to tunnel through the jump host transparently. Your session connects directly to the target server, but the traffic is relayed through the bastion. From the user's perspective it feels like a normal SSH session. You can chain multiple jump hosts with commas: ```bash # Going through two jump hosts ssh -J user1@jump1.com,user2@jump2.com target_user@final-server.com ``` Since OpenSSH 8.0 (2019), `scp` and `sftp` accept the `-J` flag too. Copy files through a jump host with: `scp -J user@jump local-file.txt target-user@target:/path/` If you're stuck on a pre-7.3 client, the legacy equivalent is: `ssh -o ProxyCommand="ssh -W %h:%p user@jump" user@target` This is rarely needed today — even CentOS 7 ships OpenSSH 7.4. Do not use `ForwardAgent yes` with jump hosts. If the jump host is compromised, an attacker can hijack your forwarded agent and authenticate as you to other servers. ProxyJump is safer because your private keys never leave your local machine — the jump host only relays encrypted traffic. OpenSSH is built into Windows 10 and 11 (Settings > Optional Features > OpenSSH Client). ProxyJump works the same way on Windows. ## SSH ProxyJump configuration with SSH config file Typing `-J` every time gets old fast. The `~/.ssh/config` file makes ProxyJump persistent: ```bash # Jump host configuration Host jumphost HostName jump.example.com User admin IdentityFile ~/.ssh/jump_key IdentitiesOnly yes # Target server using the jump host Host internal-server HostName 192.168.1.100 User ubuntu ProxyJump jumphost IdentityFile ~/.ssh/internal_key IdentitiesOnly yes ``` After this, connecting is just: ```bash ssh internal-server ``` You can use wildcards for multiple internal servers: ```bash # In ~/.ssh/config Host *.internal ProxyJump jumphost IdentitiesOnly yes ``` Now `ssh server1.internal` and `ssh server2.internal` both route through the jump host automatically. `IdentitiesOnly yes` is important here — it tells SSH to only use the explicitly configured key, not every key loaded in ssh-agent. Without this, SSH tries keys one by one and you'll hit the ["too many authentication failures"](https://www.bitdoze.com/fix-ssh-too-many-authentication-failures/) error once you accumulate enough keys in your agent. Make sure your config file has the right permissions: ```bash chmod 600 ~/.ssh/config ``` For scripted or CI connections where you can't interactively accept host keys, use `StrictHostKeyChecking=accept-new` instead of `=no`. It automatically accepts new host keys but **rejects changed keys**, so you still get warned if a server's key changes (which could indicate a MITM attack). Available since OpenSSH 7.6. `ssh -o StrictHostKeyChecking=accept-new -J user@jump target@server` ## Port forwarding through SSH jump hosts ProxyJump works with SSH port forwarding flags, which lets you access internal services that aren't SSH — databases, web UIs, monitoring dashboards. If you want a deeper dive into tunneling, see [SSH port forwarding techniques](https://www.bitdoze.com/ssh-tunneling-linux/). ### Local port forwarding (-L) Access a PostgreSQL database on an internal server from your local machine: ```bash ssh -L 5432:db.internal:5432 -J user@jump target-user@target ``` This binds local port 5432 to the database port on `db.internal` (which the target can reach). Connect to `localhost:5432` with any PostgreSQL client and the traffic is tunneled through the jump host. ### Remote port forwarding (-R) Expose a local service to the internal network: ```bash ssh -R 8080:localhost:80 -J user@jump target-user@target ``` This makes your local port 80 accessible on the target's port 8080. ### SOCKS proxy (-D) Browse the web through the internal network: ```bash ssh -D 1080 -J user@jump target-user@target ``` Configure your browser to use `localhost:1080` as a SOCKS5 proxy and all traffic routes through the jump host and target server. ## Advanced: conditional ProxyJump with Match exec If you work from multiple locations (office LAN, home, VPN), you might want different routing — direct connection from the office, jump host from everywhere else. `Match exec` handles this: ```ssh-config Match host internal-* !exec "ip addr show en0 | grep -q 192.168.1." ProxyJump home-bastion Host internal-* ProxyJump office-bastion ``` The `exec` command runs on your client before each SSH connection. It adapts automatically — no manual switching needed. Replace `en0` and `192.168.1.` with your actual interface and subnet. On Linux the interface is typically `eth0` or `wlan0`. ## Advanced: SSH multiplexing with jump hosts If you connect through a jump host frequently (Ansible, rsync, multiple terminals), multiplexing saves a lot of time. SSH can reuse a single connection to the jump host instead of re-authenticating every time: ```ssh-config Host jumphost HostName jump.example.com User admin ControlMaster auto ControlPath ~/.ssh/cm-%r@%h:%p ControlPersist 10m ``` `ControlMaster auto` tells SSH to create a persistent socket on the first connection and reuse it for subsequent connections. `ControlPersist 10m` keeps the socket open for 10 minutes after the last session closes. You can also add multiplexing on the target side: ```ssh-config Host *.internal ProxyJump jumphost ControlMaster auto ControlPath ~/.ssh/cm-%r@%h:%p ControlPersist 5m ``` The result: the first `ssh internal-server` authenticates normally. Any connection to `*.internal` within 5 minutes jumps straight through the already-open tunnel. This makes Ansible playbooks through jump hosts dramatically faster. ## Security hardening for SSH jump hosts Your jump host is the front door to your infrastructure. If it's compromised, every internal server is potentially reachable. This section covers how to lock it down properly. ![Security hardening checklist for SSH jump host configuration](../../assets/images/25/01/enhance-jumphost-security.png) ### sshd_config for bastion hosts Drop this into `/etc/ssh/sshd_config.d/50-bastion.conf` on your jump host: ```bash # /etc/ssh/sshd_config.d/50-bastion.conf # Authentication PermitRootLogin no PasswordAuthentication no KbdInteractiveAuthentication no PubkeyAuthentication yes AuthenticationMethods publickey # Session limits MaxSessions 2 MaxStartups 10:30:60 UnusedConnectionTimeout 2m # Forwarding (allowed for jump users, restricted via Match blocks below) AllowTcpForwarding yes X11Forwarding no PermitTunnel no AllowAgentForwarding no ``` Docker manipulates iptables directly and can punch holes through your carefully crafted firewall rules. Keep the jump host lean — SSH and nothing else. If you run Docker elsewhere on your network, read about [how Docker bypasses firewall rules](https://www.bitdoze.com/docker-bypasses-firewall/) so you understand the risk. ### PerSourcePenalties: built-in abuse protection Since OpenSSH 9.8 (July 2024), sshd has built-in IP penalties for repeated authentication failures, incomplete connections, and crash triggers. This is **enabled by default** — you don't need to configure anything. It reduces the need for fail2ban on bastion hosts, though they work well together for additional protection. PerSourcePenalties temporarily blocks IPs that show attack patterns. The default thresholds work for most setups. You can tune them: ```bash # In /etc/ssh/sshd_config.d/50-bastion.conf (optional) PerSourcePenalties penalty=crash:2h,authfail:1h,noauth:1h PerSourcePenaltyExemptList 10.0.0.0/8 ``` ### Dedicated jump users with Match blocks Create a restricted group for jump users on the bastion: ```bash # In /etc/ssh/sshd_config.d/50-bastion.conf Match Group jumpusers AllowTcpForwarding yes X11Forwarding no PermitTunnel no MaxSessions 2 AuthenticationMethods publickey ``` For non-jump service accounts (backups, monitoring), lock them down further: ```bash Match User backup DisableForwarding yes PermitTTY no ForceCommand /usr/local/bin/authorized-backup ``` Create the group and user: ```bash sudo groupadd jumpusers sudo usermod -aG jumpusers your-jump-user ``` ### Firewall configuration UFW rules for the jump host — deny everything except SSH from known IPs: ```bash sudo ufw default deny incoming sudo ufw default allow outgoing sudo ufw allow from 203.0.113.50/32 to any port 22 sudo ufw enable sudo ufw status verbose ``` Replace `203.0.113.50` with your office/home IP. If your IP changes frequently, consider a VPN or dynamic DNS-based allow rule. ### Authentication best practices Generate a strong ed25519 key: ```bash ssh-keygen -t ed25519 -a 100 ``` The `-a 100` flag increases KDF rounds, which slows brute-force attacks on the key file. Note: it only has effect when you set a passphrase on the key. Always set a passphrase. For high-security bastions, consider FIDO2 hardware keys (`ed25519-sk` or `ecdsa-sk`): ```bash ssh-keygen -t ed25519-sk -O resident ``` This requires a hardware security key (YubiKey, etc.) for every authentication. Private key material stays on the hardware token — even if the bastion is compromised, the key can't be extracted. ### Keep your bastion updated - Run `sudo apt update && sudo apt upgrade -y` regularly (or set up `unattended-upgrades`) - Monitor SSH logs: `journalctl -u sshd --since -1h` - Review authorized keys periodically - Keep the host lean — no extra packages, no extra services For intrusion prevention beyond PerSourcePenalties, consider [securing your VPS with CrowdSec](https://www.bitdoze.com/crowdsec-secure-server/). ## Verification: testing your setup Don't wait for production to find problems. Test your configuration before relying on it. Run `sudo sshd -t` before `sudo systemctl restart sshd`. A syntax error in your config can lock you out of your bastion host. If you're making changes over SSH itself, keep a second session open while editing. ```bash # Check OpenSSH version (client and server) ssh -V # Dump the effective config for a host alias ssh -G internal-server # Test connection with verbose output ssh -vv -J jumpuser@jump targetuser@target # Verify jump host sshd settings sudo sshd -T | grep -E 'AllowTcpForwarding|PermitTunnel|MaxSessions|PerSourcePenalties' # Test config syntax without restarting sudo sshd -t # Check that the jump users group exists getent group jumpusers ``` If `ssh -G internal-server` shows `proxyjump jumphost` in the output, your config is being read correctly. If it shows nothing, check your config file path and permissions. ## Troubleshooting SSH ProxyJump connections ### Connection refused ```bash ssh: connect to host jump-host port 22: Connection refused ``` Check if sshd is running and the port is open: ```bash sudo systemctl status sshd sudo ufw status # or sudo iptables -L -n # Test the port directly nc -zv jump-host 22 ``` If the port is open but connections are refused, check `/var/log/auth.log` for startup errors. For more on port checking, see [how to check remote ports](https://www.bitdoze.com/check-remote-port-in-linux-nc/). ### Authentication issues ```bash Permission denied (publickey) ``` Verify key permissions and that the right key is being offered: ```bash chmod 700 ~/.ssh chmod 600 ~/.ssh/id_ed25519 chmod 644 ~/.ssh/id_ed25519.pub # Check which keys SSH is trying ssh -vv -J jumpuser@jumphost targetuser@target 2>&1 | grep "Offering\|Trying" ``` If you see too many keys being tried, add `IdentitiesOnly yes` to the relevant Host block in `~/.ssh/config`. This is the most common fix for the ["too many authentication failures"](https://www.bitdoze.com/fix-ssh-too-many-authentication-failures/) error. ### ProxyJump not working ```bash # Check SSH version (needs 7.3+) ssh -V # Dump effective config for the host ssh -G internal-server # Test with full verbose output ssh -vvv -J jumpuser@jumphost targetuser@target ``` Look for lines like `proxyconnect: establishing to jump.example.com:22` in the verbose output. If you don't see ProxyJump being invoked, your config syntax might be wrong. Common config mistakes: ```bash # Wrong keywords (case-sensitive): Host jumphost Hostname jump.example.com # WRONG — should be HostName Username admin # WRONG — should be User ``` ### Permission denied after host key change If the jump host or target was reinstalled, you'll see a warning about the host key changing: ```bash @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ @ WARNING: REMOTE HOST IDENTIFICATION HAS CHANGED! @ @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ ``` If the change is expected (server rebuild, migration), remove the old key: ```bash ssh-keygen -R jump-host.example.com ``` Then reconnect and accept the new key. If the change was not expected, investigate before proceeding — it could indicate a man-in-the-middle attack. ### Network connectivity ```bash # Basic connectivity ping jump-host # Port check nc -zv jump-host 22 # Route trace traceroute jump-host ``` If you can reach the jump host but not the internal target, the problem is likely on the jump host's side — check its firewall rules, `AllowTcpForwarding` setting, and that the internal server is reachable from the jump host's network. ## Conclusion SSH jump hosts and ProxyJump are the standard way to access servers in private networks without exposing everything to the internet. Here's the quick reference: ```bash # One-time connection ssh -J jumpuser@jumphost targetuser@internal-server # Persistent config (~/.ssh/config) Host internal-server HostName internal-server User targetuser ProxyJump jumphost IdentitiesOnly yes IdentityFile ~/.ssh/internal_key ``` Key takeaways: - One hardened entry point beats exposing every server - ProxyJump makes the jump transparent — `ssh internal-server` and you're in - `~/.ssh/config` with wildcards handles dozens of servers with one rule - Lock down the bastion: no root login, no passwords, no Docker, minimal services - OpenSSH 9.8+ gives you PerSourcePenalties for free — use it - Test with `ssh -G` and `ssh -vv` before relying on the setup If you're managing multiple servers, [best self-hosted panels](https://www.bitdoze.com/best-self-hosted-panels/) can help with the broader picture, and the [Linux commands reference](https://www.bitdoze.com/linux-commands/) covers the tools you'll use alongside SSH. For managing SSH connections from a GUI, [Nexterm](https://www.bitdoze.com/nexterm-docker-install/) is worth a look.

How to Generate AI Images Locally on Mac with Flux (2026)

Sun, 09 Aug 2026 00:00:00 GMT

import Notice from "../../components/widgets/Notice.astro"; import ListCheck from "../../components/widgets/ListCheck.astro"; import Tabs from "../../components/widgets/Tabs.astro"; import Tab from "../../components/widgets/Tab.astro"; import Accordion from "../../components/widgets/Accordion.astro"; import Button from "../../components/widgets/Button.astro"; import YouTubeEmbed from "../../components/widgets/YouTubeEmbed.astro"; Generating AI images locally on a Mac is faster, cheaper, and more practical than ever in 2026. Apple Silicon's unified memory architecture handles this workload well: no discrete GPU, no cloud API bills, no uploading your prompts to someone else's server. If you've been [running AI models locally on your Mac](/lm-studio-bionic/) for text, image generation is the next thing to try. This guide covers local AI image generation on Apple Silicon using FLUX models. The recommended tool is **Draw Things**, a native macOS app that's actively maintained and much faster than the alternatives. Whether you're on an M1 with 16GB or an M4 Max with 48GB+, there's a workable path for your hardware. If you're [getting started with AI](/ai-programming-beginners-guide/) and want to see what local models can do visually, this is a good place to begin. This article was originally published in January 2025 using DiffusionBee as the recommended tool. DiffusionBee has been abandoned since August 2024 (last release v2.5.3). This guide has been completely rewritten with Draw Things as the primary tool, updated FLUX model information, and realistic performance benchmarks. ## What is FLUX? FLUX is a family of image generation models developed by Black Forest Labs. The original FLUX.1 models (dev and schnell) launched in 2024 and quickly became the go-to for local image generation on consumer hardware. Since then, the ecosystem has expanded: - **FLUX.1 dev**. High-quality output, open weights, runs on 24GB Macs with GGUF quantization. The default recommendation. - **FLUX.1 schnell**. Faster, lower quality. Good for quick drafts and iteration on 16GB Macs. - **FLUX.2 [dev]**. Released November 2025. 32 billion parameters, up to 4MP output. Excellent quality but needs ~20GB VRAM at 4-bit quantization. Only practical on 48GB+ Macs. - **FLUX.2 [klein] 4B**. Released January 2026. Apache 2.0 license (commercial use OK), fits in ~13GB. The best FLUX.2 option for 16-24GB Macs. - **FLUX 3**. Early access as of mid-2026. Multimodal (video + audio + image). API-only, not available for local use yet. For most Mac users in 2026, **FLUX.1 dev with GGUF quantization remains the sweet spot**: best quality-to-RAM ratio on 24GB machines.

Photorealistic quality that rivals commercial APIs
Open weights. Run everything locally, no internet required
Active model ecosystem with regular improvements
GGUF quantization support. Run 24GB models on 16-24GB Macs
Multiple license tiers. FLUX.2 [klein] 4B is Apache 2.0 for commercial use

These are [open-source AI models](/best-open-source-llms-claude-alternative/) with real community backing. The FLUX inference repo on GitHub has over 25,000 stars and active development from Black Forest Labs. ## Why Draw Things (Not DiffusionBee) DiffusionBee's last release was v2.5.3 on August 14, 2024, with no updates since. The project has no GGUF quantization support, no FLUX.2 support, and users report incomplete FLUX.1 features. Do not use it for new setups. **Draw Things** is a native Apple Silicon app built with SwiftUI and a custom inference engine (s4nnc). It's not a Python wrapper. It's a real macOS application distributed through the App Store with automatic updates. Why it's the recommendation:

**Native SwiftUI app**. Not Electron, not Python. Runs Metal FlashAttention directly, giving 20-40% faster generation than PyTorch MPS backends.
**App Store install**. One click, automatic updates, no terminal commands, no Python environment headaches.
**Broad model support**. FLUX.1, FLUX.2 [dev] and [klein], SD/SDXL, Z-Image, Qwen Image, and video models.
**Actively maintained**. Latest release July 17, 2026, with dozens of releases in the past year.
**Free base tier**. No cost to use. Optional Draw Things+ at $8.99/mo adds cloud compute offload (useful for 8GB Macs).
**Cross-device**. Same app runs on Mac, iPhone, and iPad with parameter sync via iCloud.

The speed difference is real. On an M4 Pro with 24GB RAM, DiffusionBee took about 6 minutes to generate a single FLUX.1 dev image at 704x704 with 25 steps. Draw Things generates at 1024x1024 with 20 steps in roughly 50 seconds. Higher resolution, fewer steps, 7x faster. ## GGUF quantization: how FLUX runs on your Mac FLUX.1 dev is a 12-billion parameter model. The full FP16 weights are about 24GB. That won't fit in 24GB of unified memory alongside macOS and other apps. GGUF quantization solves this by reducing the precision of the model weights, shrinking the file size at the cost of a small quality reduction. Here's how the quantization levels break down: | Quantization | File size | Quality | RAM needed | Best for | |-------------|-----------|---------|------------|----------| | FP16 (original) | ~24GB | Best | 48GB+ | Maximum quality | | Q8 | ~13GB | Near-lossless | 32GB+ | High quality | | Q6_K | ~10GB | Best balance | 24GB | **Sweet spot for M4 Pro** | | Q4_KS | ~7GB | Some loss | 16GB | 16GB Macs | | Q2_K | ~4GB | Noticeable loss | 16GB | Emergency only | The key insight: **Q6_K at ~10GB gives you nearly the same visual quality as the full model while fitting comfortably in 24GB unified memory.** You'll see the difference in extremely fine details (text in images, tiny patterns), but for most use cases it's indistinguishable. Draw Things handles GGUF models automatically. You pick the quantization level from the model selector and it downloads the right file. No manual conversion needed. If you need to [free up disk space on your Mac](/mac-find-big-files/) before downloading these models, do that first. Each model file is 7-13GB. **Model**: FLUX.1 dev (Q6_K) **File size**: ~10GB **Quality**: Near-lossless. Best balance of speed and fidelity **Generation time**: ~50 seconds at 1024×1024, 20 steps (M4 Pro) **RAM usage**: ~7GB during generation, 50% GPU utilization This is the sweet spot. If you have an M4 Pro or M4 Mac Studio with 24GB+, start here. **Model**: FLUX.1 schnell (Q4_KS) or FLUX.2 [klein] 4B **File size**: ~7GB (schnell) or ~13GB (klein 4B) **Quality**: Noticeable quality reduction vs Q6_K, but still good for blog images and social media **Generation time**: ~30-45 seconds at 1024×1024 **RAM usage**: Tight. Close other apps before generating FLUX.1 schnell trades quality for speed and lower RAM. FLUX.2 [klein] 4B is a newer alternative that fits in 13GB. Worth trying if you want better quality than schnell. **Model**: FLUX.1 dev (FP16 or Q8) or FLUX.2 [dev] (Q4) **File size**: 13-24GB **Quality**: Best possible from FLUX models **Generation time**: ~30-40 seconds at 1024×1024 (FLUX.1), ~60 seconds (FLUX.2 dev) **RAM usage**: Comfortable headroom You can run full-precision FLUX.1 or try FLUX.2 [dev] at 32B parameters. This is the professional tier. ## Step-by-step: generate images with Draw Things ### 1. Install Draw Things The easiest path is the Mac App Store: 1. Open the **App Store** on your Mac. 2. Search for **"Draw Things"**. 3. Click **Get** / **Install**. 4. Wait for the download (~200MB app, models are separate). Alternatively, download directly from [drawthings.ai/downloads](https://drawthings.ai/downloads/). **Verify**: Draw Things appears in your Applications folder and launches without errors. ### 2. Download a FLUX model 1. Open Draw Things. 2. Click the **model selector** at the top of the screen. 3. Scroll to the FLUX section. 4. Choose your model: - **24GB Mac**: Select "FLUX.1 dev" with Q6_K quantization - **16GB Mac**: Select "FLUX.1 schnell" with Q4_KS quantization 5. Click download and wait. The Q6_K model is ~10GB — this takes a few minutes depending on your connection. **Verify**: The model name appears in the selector, and disk usage increases by the expected file size. You can check with `du -sh ~/Library/Containers/com.liuliu.draw-things/` in Terminal if you want to confirm. ### 3. Write your prompt and generate 1. Enter your prompt in the text field at the bottom of the screen. 2. Recommended starting settings: - **Steps**: 20 - **Sampler**: Euler - **Resolution**: 1024×1024 - **Guidance scale**: 3.5 (default for FLUX) 3. Click **Generate**. **Verify**: An image appears in under 2 minutes on a 24GB Mac. On M4 Pro hardware with Q6_K, expect ~50 seconds. GPU activity will be visible in Activity Monitor under the GPU tab. After your first generation, confirm three things: the image renders without visual corruption, generation time is under 2 minutes on 24GB Mac hardware, and you can see GPU usage in Activity Monitor during generation. If any of these fail, check the Troubleshooting section below. ### 4. Adjust settings for quality vs speed Once you've confirmed the basic workflow works, tune for your needs: - **Fewer steps (10–15)**: Faster generation, slightly lower quality. Good for quick iterations and prompt testing. - **More steps (25–30)**: Slower, marginal quality gain. Not worth it for most images. - **Resolution tradeoffs**: 768×768 for speed, 1024×1024 for quality, 1280×1280 if your RAM allows. - **Seed**: Lock a seed to reproduce good results with prompt tweaks. The default settings (20 steps, Euler, 1024×1024) are a good baseline. Adjust one variable at a time so you know what changed. ## Alternative: ComfyUI for power users ComfyUI is overkill for most users. Start with Draw Things. Move to ComfyUI when you need custom workflows, batch processing, or models that Draw Things doesn't support. If you just want to generate images from text prompts, Draw Things is the better experience on Mac. ComfyUI is a node-based workflow engine that gives you maximum control over the image generation pipeline. It's the tool of choice for people who build custom workflows — chaining models, applying ControlNet, doing inpainting pipelines, or batch processing hundreds of images. Installation options: ```bash # Install prerequisites brew install python@3.11 git # Clone ComfyUI git clone https://github.com/comfyanonymous/ComfyUI.git cd ComfyUI python3.11 -m venv venv source venv/bin/activate pip install -r requirements.txt ``` After installation: 1. Launch ComfyUI from your Applications folder. 2. Go to **Settings → GPU Backend** and select **MPS** (not CPU. This is critical for Apple Silicon performance). 3. Install the **ComfyUI-GGUF** plugin for quantized model support. 4. Install **ComfyUI Manager** for easy node management. 5. Download a GGUF model file (e.g., FLUX.1 dev Q6_K from HuggingFace). 1. Download the official macOS DMG from [download.comfy.org](https://download.comfy.org/mac/dmg/arm64). 2. Open the DMG and drag ComfyUI to Applications. 3. Launch and select **MPS** as GPU backend in Settings. 4. Install the **ComfyUI-GGUF** plugin and **ComfyUI Manager**. 5. Download a GGUF model file. ComfyUI has the broadest model support of any local tool — FLUX.1, FLUX.2, SD series, and more. The tradeoff is a steep learning curve. If you want to [integrate AI image generation into automated workflows](/mastra-image-agent-kie-ai/), ComfyUI's API and node system make that possible. ## Which FLUX model should you use? With multiple FLUX model generations available, choosing the right one depends on your hardware and use case. - **Parameters**: 12B - **RAM needed**: 24GB (with Q6_K GGUF) - **Quantization options**: Q2_K through FP16 - **License**: FLUX Non-Commercial License (personal use OK, commercial use requires separate license) - **Quality**: Best-in-class for the RAM requirement. Photorealistic output, good text rendering. - **Best for**: Daily image generation on M4 Pro 24GB or similar. The default recommendation. - **Generation time**: ~50 seconds at 1024×1024, 20 steps on M4 Pro (Draw Things) - **Parameters**: 12B (distilled) - **RAM needed**: 16GB (with Q4_KS GGUF) - **Quantization options**: Q4_KS, Q2_K - **License**: Apache 2.0 (commercial use OK) - **Quality**: Noticeably lower than dev, but fast. Good enough for blog images and social media. - **Best for**: Quick iterations, prompt testing, 16GB Macs that can't run dev comfortably. - **Generation time**: ~30 seconds at 1024×1024 - **Parameters**: 4B - **RAM needed**: 16–24GB (~13GB file) - **Quantization options**: GGUF variants available - **License**: Apache 2.0 (commercial use OK) - **Quality**: Lower than FLUX.1 dev, but much faster. Good for interactive use and prototyping. - **Best for**: Users who want FLUX.2 features (multi-reference input, HEX color support) without 48GB RAM. Released January 2026. - **Generation time**: Sub-second to a few seconds on capable hardware - **Parameters**: 32B - **RAM needed**: 48GB+ (~20GB at 4-bit quantization) - **Quantization options**: Q4 and above - **License**: FLUX Non-Commercial License - **Quality**: Excellent. Supports up to 4MP output, multi-reference (up to 10 images), HEX color control. - **Best for**: Professional work on M4 Max or M4 Ultra with 48GB+ unified memory. - **Generation time**: ~60 seconds at 1024×1024 on M4 Max - **Status**: Early access (mid-2026), API-only - **Capabilities**: Multimodal — video, audio, and image generation in one model. Self-Flow architecture. - **Local availability**: Not yet. Will likely need significant hardware when it lands. If you need FLUX-level quality without buying a 48GB Mac, [cloud-based AI image APIs like Kie.ai](https://go.bitdoze.com/kie-ai) offer access to the latest models without hardware constraints. Check the [Kie.ai review](/kie-ai-review/) for pricing details. ## Performance benchmarks: what to expect All numbers below are from community reports on M4 Pro 24GB hardware. Your results will vary based on quantization, resolution, steps, and what else is running on your Mac. | Tool | Model | Resolution | Steps | Time | |------|-------|-----------|-------|------| | **Draw Things** | FLUX.1 dev (Q6_K) | 1024×1024 | 20 | **~50 seconds** | | **ComfyUI (MPS)** | FLUX.1 dev (Q6_K) | 1024×1024 | 20 | ~50–90 seconds | | DiffusionBee (old) | FLUX.1 dev | 704×704 | 25 | ~6 minutes | The 7x speed improvement from DiffusionBee to Draw Things is primarily due to Metal FlashAttention — Draw Things' proprietary Apple Silicon optimization that bypasses PyTorch's MPS backend. Draw Things also generates at a higher resolution (1024×1024 vs 704×704) in less time. These benchmark numbers are from community reports. Generation speed depends on your specific Mac, the model quantization, resolution, number of steps, and background processes. Close Chrome and other heavy apps before benchmarking — they compete for the same unified memory. M5 Macs with Neural Accelerators should see further improvements. Draw Things explicitly optimizes for M5 hardware with Metal FlashAttention v2.5. ## Hardware recommendations by Mac model Not every Mac can run every model. Here's what to expect: | Mac config | SD 1.5 | SDXL | FLUX.1 | FLUX.2 | Notes | |-----------|--------|------|--------|--------|-------| | M1 / 8GB | ✅ | 🟡 Slow | ❌ | ❌ | Basic experimentation only | | M2 / 16GB | ✅ | ✅ | 🟡 (Q4_KS) | ❌ | Light use, blog images | | M4 Pro / 24GB | ✅ | ✅ | ✅ (Q6_K) | 🟡 (klein 4B) | Daily creation — sweet spot | | M4 Max / 48GB+ | ✅ | ✅ | ✅ (FP16) | ✅ (dev Q4) | Professional tier | | M5 / any RAM | ✅ | ✅ | ✅ | ✅ | Latest hardware, best performance |

Apple Silicon Mac (M1 or newer) — Intel Macs won't work well
16GB+ RAM minimum for FLUX — 24GB recommended for comfortable generation
macOS 13 Ventura or newer
~15GB free disk space for model + app (Q6_K model is ~10GB)
SSD strongly recommended — model loading from external HDD is painfully slow

If you're considering a Mac Mini specifically as an AI workstation, it's one of the best value options for local inference. See the [best mini PC for home server](/best-mini-pc-home-server/) roundup for a full comparison — the Mac Mini M4 punches well above its price for AI workloads. The M4 Mac Studio (released March 2025) scales up to M4 Max with 128GB unified memory, which is overkill for image generation but useful if you also run large language models locally. ## Troubleshooting common issues **Cause**: The most common culprit is the GPU backend not being used. On ComfyUI, this means MPS isn't selected — the model falls back to CPU inference, which is 50–100x slower. **Fix**: 1. In ComfyUI, verify **Settings → GPU Backend → MPS** is selected. 2. In Draw Things, this is handled automatically — if you see extreme slowness, restart the app. 3. Open Activity Monitor → CPU tab. If CPU usage is maxed out during generation (instead of GPU), the model is running on CPU. **Verify**: During generation, Activity Monitor should show significant GPU utilization. CPU usage should be moderate, not maxed. **Cause**: Insufficient RAM. The model needs to fit in unified memory alongside macOS and other apps. Chrome alone can consume 4–8GB. **Fix**: 1. Close all unnecessary applications before loading a model — especially Chrome, Electron apps, and anything with a large memory footprint. 2. Open Activity Monitor → Memory tab. Check "Memory Pressure." If it's yellow or red, you don't have enough free RAM. 3. Switch to a smaller quantization: if Q6_K crashes, try Q4_KS. If Q4_KS crashes, try FLUX.1 schnell instead of dev. **Verify**: Model loads without error and memory pressure stays green in Activity Monitor. **Cause**: Sampler/model mismatch. Some samplers don't work well with FLUX models. **Fix**: 1. Stick to **Euler** or **DPM++** samplers for FLUX. Avoid exotic samplers like DDIM or LMS. 2. Reset settings to defaults if you've been experimenting. 3. If using ComfyUI, make sure your workflow connects the VAE correctly — a missing or wrong VAE produces garbage output. **Verify**: Regenerate with Euler sampler, 20 steps, default guidance scale. Output should be a coherent image. **Cause**: Model files are large (7–13GB). Unstable connections or disk space issues can interrupt downloads. **Fix**: 1. Draw Things handles downloads automatically with resume support — just retry. 2. Check available disk space first. You need at least as much free space as the model file size. 3. For manual downloads (ComfyUI), use a download manager or `curl -C -` to resume interrupted downloads. 4. If you're on a slow connection, consider downloading FLUX.1 schnell (smaller) first to verify the workflow, then download the larger model overnight. **Verify**: Model file exists on disk and matches expected size. In Draw Things, the model appears in the selector with a checkmark. ## Cost comparison: local vs cloud Generating images locally is essentially free after the hardware cost. Here's how the economics break down: | Approach | Cost | Per-image cost | Notes | |----------|------|---------------|-------| | **Draw Things (local)** | Free | $0 (electricity negligible) | Base tier is free, no API keys needed | | **Draw Things+ (cloud offload)** | $8.99/mo | Included | Useful for 8GB Macs that can't run models locally | | **ComfyUI (local)** | Free | $0 | Open source, no account needed | | **Black Forest Labs API** | Pay per use | $0.014–$0.07/image | For FLUX.2 [pro], [klein], [max] via API | The breakeven is fast. If a cloud API charges $0.03/image, you'd spend $15 for 500 images. Draw Things generates those same 500 images for free on hardware you already own. If you generate images weekly, local is the clear winner. The case for cloud: if you need FLUX.2 [dev] (32B params) or FLUX 3 and you don't have 48GB+ RAM, [cloud AI image APIs like Kie.ai](https://go.bitdoze.com/kie-ai) give you access without buying new hardware. The [Kie.ai review](/kie-ai-review/) covers pricing and capabilities in detail. After roughly 500 images, local generation pays for itself vs cloud API pricing. If you generate images even casually — blog posts, social media, creative projects — local is the way to go. ## Tips for optimal performance

**Close Chrome before generating.** It's the single biggest memory hog on most Macs. Safari uses less RAM if you need a browser open.
**Use 20 steps for normal images, 10–15 for drafts.** Going above 25 steps adds time with minimal quality gain on FLUX models.
**Keep models on your internal SSD.** Loading models from external drives or network storage adds significant delay.
**Try FLUX.1 schnell for quick iterations.** It's faster than dev — use it to nail your prompt, then switch to dev for the final render.
**Monitor RAM pressure in Activity Monitor.** If you see yellow or red memory pressure during generation, close more apps or use a smaller quantization.
**Batch similar prompts together.** The model stays loaded in memory between generations in Draw Things, so consecutive images are faster than the first.
**Restart Draw Things if generation gets slow over time.** Memory fragmentation can degrade performance after extended sessions.

## Conclusion Generating AI images locally on Mac in 2026 is a solved problem. Draw Things gives you a one-click install from the App Store, automatic model management, and generation speeds that would have been unthinkable two years ago. FLUX.1 dev with GGUF quantization hits the quality sweet spot on 24GB Macs, and the model ecosystem keeps expanding. Start with Draw Things. It's free, it's fast, and it handles the complexity for you. If you eventually need custom workflows or batch processing, ComfyUI is the upgrade path — but most people won't outgrow Draw Things. For models that need more RAM than you have — FLUX.2 [dev] at 32B parameters, or FLUX 3 when it becomes available — [cloud AI generation with Kie.ai](https://go.bitdoze.com/kie-ai) is a practical fallback. But for everyday image generation, local is cheaper, faster (no network round-trip), and private. If you're also interested in [running AI models locally](/ollama-docker-install/) for text generation, the same Apple Silicon hardware that handles FLUX will run local LLMs through Ollama. Your Mac is a surprisingly capable AI workstation — you just need to point the right tools at it.

Find the Largest Files on Your Mac (Simple Script & Tools)

Sun, 09 Aug 2026 00:00:00 GMT

Open Finder and press Cmd + F
Click "This Mac" to search the entire drive (not just the current folder)
Click the first dropdown → select "File Size"
Set the condition to "is greater than"
Enter a threshold: 1 GB (adjust to 500 MB for smaller drives, or 5 GB if you only want the biggest offenders)
Click the "Size" column header to sort results largest-first

On a 256 GB drive, start with 500 MB. On a 1 TB+ drive, start with 1 GB. You'll get a manageable list instead of hundreds of results. Finder search has limits: it won't show hidden directories (`~/Library`, `~/.ollama`), system files, or files inside app bundles. For those, you need Terminal methods. ## Spotlight CLI: `mdfind` for instant results `mdfind` queries the Spotlight index, making it near-instant compared to walking the filesystem with `find`. It's the fastest way to locate large files if Spotlight indexing is enabled. ```bash # Find all files > 1 GB using Spotlight index (near-instant) mdfind "kMDItemFSSize > 1000000000" -onlyin ~/ 2>/dev/null | \ while IFS= read -r f; do stat -f '%z %N' "$f" 2>/dev/null done | sort -rn | head -20 ``` ```bash # Find all files > 500 MB in your home directory mdfind "kMDItemFSSize > 500000000" -onlyin ~/ 2>/dev/null | \ while IFS= read -r f; do stat -f '%z %N' "$f" 2>/dev/null done | sort -rn | head -20 ``` The output shows byte sizes and full paths, sorted largest-first. You can pipe it through `numfmt --to=iec` for human-readable sizes, though `stat` on macOS doesn't have the GNU `numfmt` by default. If `mdfind` returns empty or incomplete results, Spotlight may be disabled or rebuilding. Check with:

mdutil -s /

If it says indexing is disabled, re-enable it with:

sudo mdutil -E /

Rebuilding the index takes 10-30 minutes depending on drive size. **Caveat:** `mdfind` only finds files that Spotlight has indexed. Some system directories and external drives may not be indexed. For a comprehensive scan, use the Bash script below. ## The Bash script: full system scan This is the core method — an improved macOS-optimized script that scans your filesystem, reports disk usage, and lists the largest files. The original version of this script had issues with modern macOS permissions and scanned external drives. This version fixes both. ### Prerequisites: Full Disk Access Since macOS Mojave (10.14), even `sudo` can't access certain user directories without Terminal having **Full Disk Access**. Without it, the script silently skips entire directory trees. The `2>/dev/null` hides the "Operation not permitted" errors. Without this setting, the script silently skips ~/Library, Mail attachments, Messages, Photos databases, and other large files. You'll get incomplete results without knowing it. **Grant Full Disk Access:** 1. Open **System Settings > Privacy & Security > Full Disk Access** 2. Click the **+** button 3. Navigate to `/Applications/Utilities/Terminal.app` (or your terminal of choice, like [Ghostty](/ghostty-terminal/) or [WezTerm](/install-wezterm-mac/)) 4. Toggle it **ON** 5. **Quit and reopen** the terminal for changes to take effect

macOS 12 (Monterey) or later
Terminal.app (or Ghostty/WezTerm) added to Full Disk Access
Homebrew installed (needed later for CLI tools like dust and gdu). Install from brew.sh.

### The improved script Key changes from the original: - Scans your **home directory** by default (where most user files live), with `--all` flag for power users - Uses `-x` to stay on one filesystem (won't wander into external drives or network mounts) - Excludes noisy directories that waste scan time - Safer output parsing with `IFS=$'\t'` - Adds a Time Machine snapshot check at the end ```bash #!/bin/bash # Find the largest files on your Mac # Usage: ./find_large_files.sh [number_of_files] # ./find_large_files.sh --all [number_of_files] (scan entire system) # Parse arguments scan_path="$HOME" num_files=20 if [[ "$1" == "--all" ]]; then scan_path="/" shift fi if [[ -n "$1" && "$1" =~ ^[0-9]+$ ]]; then num_files=$1 fi # Print disk space information echo "===========================================" echo "DISK SPACE INFORMATION" echo "===========================================" df -h "$scan_path" | awk 'NR==2 { printf "Total Space: %s\n", $2 printf "Used Space: %s\n", $3 printf "Free Space: %s\n", $4 printf "Usage: %s\n", $5 }' echo "===========================================" echo # Build exclusion list. Skip directories that waste time or produce noise excludes=( -not $ -path "/System/*" -prune $ -not $ -path "/Volumes/*" -prune $ -not $ -path "/private/var/vm/*" -prune $ -not $ -path "/private/var/folders/*" -prune $ -not $ -path "*/Library/Caches/*" -prune $ -not $ -path "*/Library/Containers/*" -prune $ -not $ -path "*/node_modules/*" -prune $ ) echo "Searching for the $num_files largest files..." echo "Scanning: $scan_path" echo "This may take a minute on large drives." echo # Create temporary file for results tmp_file=$(mktemp) # Run the scan. -x keeps us on one filesystem # sudo is needed when scanning / or other users' directories if [[ "$scan_path" == "/" ]]; then sudo find "$scan_path" -x "${excludes[@]}" \ -type f -print0 2>/dev/null | \ xargs -0 du -h 2>/dev/null | \ sort -rh | \ head -n "$num_files" > "$tmp_file" else find "$scan_path" -x "${excludes[@]}" \ -type f -print0 2>/dev/null | \ xargs -0 du -h 2>/dev/null | \ sort -rh | \ head -n "$num_files" > "$tmp_file" fi # Print formatted results echo "===========================================" echo "TOP $num_files LARGEST FILES" echo "===========================================" echo printf "%-8s | %s\n" "Size" "File Path" echo "-------------------------------------------" while IFS=$'\t' read -r size file; do printf "%-8s | %s\n" "$size" "$file" done < "$tmp_file" echo "===========================================" rm "$tmp_file" # Check for Time Machine local snapshots echo echo "===========================================" echo "TIME MACHINE LOCAL SNAPSHOTS" echo "===========================================" snapshots=$(tmutil listlocalsnapshots / 2>/dev/null) if [[ -n "$snapshots" ]]; then count=$(echo "$snapshots" | wc -l | tr -d ' ') echo "Found $count local snapshot(s). These are invisible to find/du:" echo "$snapshots" | head -5 if (( count > 5 )); then echo " ... and $((count - 5)) more" fi echo echo "To reclaim this space: sudo tmutil thinlocalsnapshots / 999999999999 4" else echo "No local snapshots found." fi echo "===========================================" echo echo "Scan complete!" ``` ### Run the script step-by-step 1. **Open Terminal.** Find it in Applications > Utilities or press `Cmd + Space` and type "Terminal". If you want a better terminal experience, consider setting up [Fish shell on macOS](/fish-shell-macos-setup/) for better autocomplete and syntax highlighting. 2. **Create the script file:** ```bash nano ~/find_large_files.sh ``` Paste the script above, then save with `Ctrl + X`, `Y`, `Enter`. 3. **Make it executable:** ```bash chmod +x ~/find_large_files.sh ``` 4. **Run it:** ```bash # Scan your home directory (default, no sudo needed) ./find_large_files.sh # Show top 30 files instead of 20 ./find_large_files.sh 30 ``` ```bash # Scan the entire system (requires sudo for /System, /private, etc.) ./find_large_files.sh --all # Full scan, top 50 files ./find_large_files.sh --all 50 ``` When running a full system scan, you'll be prompted for your password. The scan takes 1-5 minutes depending on drive size and whether you have external drives connected. The disk space header uses df (filesystem-level view) while the file list uses du (sums individual file sizes). On APFS, these numbers can differ significantly due to clones, sparse files, and purgeable space. See the "Hidden Space Eaters" section below. Don't panic if the math doesn't add up. For long scans, consider running it inside a [tmux terminal multiplexer](/tmux-basics/) so you can detach and come back later. **Sample output (home directory scan):** ``` =========================================== DISK SPACE INFORMATION =========================================== Total Space: 460Gi Used Space: 95Gi Free Space: 341Gi Usage: 22% =========================================== Searching for the 20 largest files... Scanning: /Users/dragos This may take a minute on large drives. =========================================== TOP 20 LARGEST FILES =========================================== Size | File Path ------------------------------------------- 13G | /Users/dragos/.diffusionbee/downloaded_assets/FLUX.1-schnell_flux_schnell_q5p_NNC_all.sqlite 13G | /Users/dragos/.diffusionbee/downloaded_assets/FLUX.1-dev_flux_dev_q5p_NNC_all.sqlite 8.4G | /Users/dragos/.ollama/models/blobs/sha256-6e41c39f4490a9e8b7a65916425c6ed97f04ed95bab991c4ab6a462ff84d1608 1.9G | /Users/dragos/.ollama/models/blobs/sha256-dde5aa3fc5ffc17176b5e8bdc82f587b24b2678c6c66101bf7da77af9f7ccdff 949M | /Applications/DaVinci Resolve/DaVinci Resolve.app/Contents/MacOS/Resolve ... =========================================== TIME MACHINE LOCAL SNAPSHOTS =========================================== Found 3 local snapshot(s). These are invisible to find/du: com.apple.TimeMachine.2025-01-09-183042.local com.apple.TimeMachine.2025-01-09-193042.local com.apple.TimeMachine.2025-01-09-203042.local To reclaim this space: sudo tmutil thinlocalsnapshots / 999999999999 4 =========================================== ``` If the output shows mostly `/System` or `/Volumes` paths, the `-x` flag or exclusions aren't working. Check that you're running the updated script, not the old version. **Verify:** The disk info header should show your actual drive size and usage. The file list should contain user-level paths (home directory, Applications), not system internals. ## Modern CLI tools: `dust`, `gdu` & `ncdu` If you find yourself running disk cleanup regularly, a one-shot script isn't the best tool. These three CLI utilities give you interactive, browsable views of disk usage, much better for exploring and deleting on the fly. All three install via [Homebrew](https://brew.sh): ```bash brew install dust ``` `dust` shows the largest directories and files as a proportional tree visualization. It's fast (Rust-based) and the output is immediately readable without navigating a TUI. ```bash dust ~/ # full home directory tree dust -F ~/ # files only, no directory summaries dust -n 30 ~/ # show top 30 entries dust -d 2 ~/ # limit depth to 2 levels (quick overview) ``` GitHub: [bootandy/dust](https://github.com/bootandy/dust), 12k stars, actively maintained. ```bash brew install gdu ``` `gdu` is a fast interactive disk analyzer with arrow-key navigation. It uses parallel processing, making it significantly faster than `ncdu` on SSDs. You can navigate into directories and delete files directly. ```bash gdu ~/ # interactive mode. Arrow keys to navigate, 'd' to delete gdu -t 20 ~/ # non-interactive: top 20 largest items ``` GitHub: [dundee/gdu](https://github.com/dundee/gdu), 5.9k stars, Go-based. ```bash brew install ncdu ``` `ncdu` (NCurses Disk Usage) has been the go-to TUI disk analyzer for over a decade. It's slower than `gdu` on modern SSDs but it's available everywhere: Linux, BSD, macOS. The interface is familiar to most sysadmins. ```bash ncdu ~/ # scan and browse interactively ncdu -x / # scan root filesystem, don't cross mount points ``` Use dust when you want a quick visual overview without leaving the command output. Use gdu when you want to interactively explore and delete files. Use ncdu if you're on a system where it's already installed (it's everywhere). All three are free and open source. If you spend a lot of time in the terminal, you can [supercharge your Fish shell with plugins](/best-fish-shell-plugins/) for better tab completion on these commands. ## Where is my "missing" disk space? You ran `df` and it says 200 GB used. You ran `du` on your home directory and it only adds up to 120 GB. Where did the other 80 GB go? On APFS (the default filesystem since High Sierra), the answer is usually one of three things. ### Time Machine local snapshots Time Machine stores hourly local snapshots directly on your startup disk. These can consume **tens of GB** but are completely invisible to `find`, `du`, and Finder. They don't show up as files because they're filesystem-level snapshots. ```bash # Check if snapshots are eating your space tmutil listlocalsnapshots / # If you see many snapshots and need space now: sudo tmutil thinlocalsnapshots / 999999999999 4 ``` The `thinlocalsnapshots` command tells macOS to purge local snapshots, freeing space immediately. The priority parameter (`4`) means "low priority." It won't interrupt other operations. These snapshots auto-delete when disk pressure occurs, but manual thinning is safe if you need space now. These won't show up in Finder, du, or the script output. Always check with tmutil if you're mysteriously low on space. The snapshots are separate from your Time Machine backup drive — thinning local snapshots doesn't affect your backups. ### APFS clones, sparse files & purgeable space APFS has features that make `du` output misleading: - **Clones:** `cp -c` (and many apps like pnpm, uv, git worktrees) creates copy-on-write clones. `du` reports the full size of every clone, but deleting one clone frees **zero** blocks if another clone exists. A `node_modules` tree can report 20 GB in `du` but deleting it frees 3 MB. - **Sparse files:** Docker's `Docker.raw` disk image and VM images (UTM, Parallels) are sparse files. They report as 64 GB but only occupy the actually-written blocks (e.g., 9 GB). If you're running Docker, see how to [clean up Docker images and reclaim disk space](/cleanup-all-docker-things/). - **Purgeable space:** macOS marks some files as purgeable (caches, local snapshots, iCloud-offloaded files). They count as "used" in `du` but macOS will auto-delete them when space is needed. You can check purgeable space with: ```bash diskutil info / | grep -i purgeable ``` df shows real filesystem-level usage (what the kernel reports). du sums individual file sizes. On APFS, clones, sparse files, and purgeable space cause these numbers to diverge significantly. When in doubt, trust df for "how much space is actually used" and du for "which files are the biggest." If you're generating [locally AI images like Flux models](/ai-images-mac/), those model files can be 10-13 GB each — and DiffusionBee stores them in `~/.diffusionbee/downloaded_assets/`. ## What's safe to delete (and what never to touch) The script finds large files but doesn't tell you what's safe to remove. Here's a practical guide organized by category. **Ollama models** — stored in `~/.ollama/models/`. Each model is 2-13 GB. Use the proper CLI to remove them (raw `rm` leaves orphaned blobs): ```bash ollama list # see what's installed ollama rm # remove a specific model ``` See the full [Ollama setup guide](/ollama-docker-install/) for managing models properly. **DiffusionBee models** — stored in `~/.diffusionbee/downloaded_assets/`. These are the largest files on many Macs (13 GB each for FLUX models). You can delete the `.sqlite` files directly if you no longer use DiffusionBee. Docker's disk usage adds up fast. Check what's consuming space: ```bash docker system df # see Docker's disk usage breakdown docker system prune -a # remove all unused images, containers, networks (careful!) docker image prune # remove dangling images only (safer) ``` Docker's `Docker.raw` disk image (in `~/Library/Containers/com.docker.docker/`) can be 50+ GB as a sparse file. Its reported size vs. actual disk usage will differ. See the full [Docker cleanup guide](/cleanup-all-docker-things/) for a detailed walkthrough. These are all safe to delete — they regenerate on next use: ```bash # Homebrew cache (old downloads) brew cleanup -s # npm cache npm cache clean --force # pip cache pip cache purge # yarn cache yarn cache clean ``` Project-level directories safe to delete (they rebuild): - `node_modules/` — run `npm install` to regenerate - `.venv/` or `venv/` — run `python -m venv .venv` to recreate - `.next/` — Next.js build cache, regenerates on `npm run build` - `target/` — Rust build output, regenerates on `cargo build` - `__pycache__/` — Python bytecode, regenerates automatically If you've ever had Xcode installed, old device support files pile up: ```bash # Old iOS/tvOS/watchOS device support (can be many GB) rm -rf ~/Library/Developer/Xcode/iOS\ DeviceSupport/* # Old Xcode caches rm -rf ~/Library/Developer/Xcode/DerivedData/* # Old simulator data xcrun simctl delete unavailable ``` Do NOT remove anything in these locations unless you know exactly what you're doing:

• /System — macOS system files
• /usr (except /usr/local) — system binaries
• /Library/Extensions — kernel extensions
• /Library/PreferencePanes — system preference panes
• Any file you can't identify in a system directory

When in doubt, don't delete it. Move it to Trash first and see if anything breaks before emptying. If you're unsure whether two directories contain the same content before deleting one, you can [compare folder contents in Terminal](/compare-folders-content-differences/) to check. ## Related terminal tools If you're spending time in Terminal for disk cleanup and system management, these tools make the experience better: - **[Ghostty](/ghostty-terminal/)** — modern, GPU-accelerated terminal emulator for macOS - **[WezTerm](/install-wezterm-mac/)** — terminal with built-in tmux-like multiplexing - **[tmux](/tmux-basics/)** — terminal multiplexer for long-running scans and multiple sessions - **[Fish shell](/fish-shell-macos-setup/)** — better default shell with autosuggestions and syntax highlighting - **[cmux](/cmux-terminal/)** — AI-assisted terminal sessions for power users ## Conclusion You don't need paid apps to find and manage large files on your Mac. Between Finder search for quick checks, `mdfind` for instant results, the Bash script for comprehensive scans, and `dust`/`gdu`/`ncdu` for interactive exploration, you have everything you need. The real disk hogs are usually AI models (Ollama, DiffusionBee, Stable Diffusion), Docker images, Time Machine local snapshots, and dev project caches. Run the script once a month or whenever you see the "Your disk is almost full" warning. Apple charges $0.99/month for 50 GB of iCloud storage — but cleaning up local files is free.

Best Self-Hosted Airtable Alternatives in 2026

Sat, 08 Aug 2026 00:00:00 GMT

import Notice from "@components/widgets/Notice.astro"; import Accordion from "@components/widgets/Accordion.astro"; import Button from "@components/widgets/Button.astro"; Airtable costs $20–45 per seat per month in 2026. For a 10-person team on the Business plan, that's $5,400/year, and you still don't own your data. If you're evaluating self-hosted Airtable alternatives, this guide compares six tools you can deploy with Docker on a cheap VPS tonight: NocoDB, Teable, Baserow, Grist, undb, and Mathesar. I'll cover licensing reality (NocoDB is no longer open source), feature differences, Docker commands, and operator notes on database backends and backups. No feature tourism. Everything here runs on a single VPS with Docker Compose. If you want more self-hosted apps for your stack, check [best self-hosted apps for your business](https://www.bitdoze.com/docker-containers-business/). ## Overview of Airtable and its popularity Airtable combines a spreadsheet interface with relational database power. Features like customizable views (Grid, Calendar, Kanban, Gallery), rich field types, automations, and integrations made it the default choice for non-technical teams who outgrew spreadsheets. That popularity came with a pricing restructure in 2025–2026. The old Plus plan ($10/user/mo) was replaced by Team ($20/user/mo annual, $24 monthly). Business is now $45/user/mo annual. For a 50-person team, that's $27,000/year. Other reasons teams move to self-hosted alternatives: - **Data sovereignty**: your data lives on Airtable's servers - **Vendor lock-in**: exporting linked records and automations is painful - **Row/record limits**: Airtable caps records per base depending on your plan - **Privacy**: sensitive data in a third-party SaaS raises compliance questions ## Understanding self-hosted database solutions Self-hosted in this context means running these tools as Docker containers on infrastructure you control: a VPS, a mini PC, or a NAS. All six tools in this article deploy with a single `docker run` or `docker-compose up`. Benefits of self-hosting: 1. **Data control**: you own the data, the backups, and the access policies 2. **Customization**: deeper configuration than any SaaS allows 3. **Cost control**: flat monthly VPS cost regardless of team size 4. **Privacy**: data never leaves your infrastructure 5. **Performance**: tune hardware and network for your workload The tradeoff is you handle server management, security updates, and backup planning. If you're already running Docker containers, this is familiar territory. ## Where you can host Airtable alternatives ### VPS server with Hetzner, DigitalOcean, etc. A VPS is the fastest path to a running instance. Providers like [Hetzner](https://go.bitdoze.com/hetzner), [Hostinger](https://go.bitdoze.com/hostinger-vps), [DigitalOcean](https://go.bitdoze.com/do), and [Vultr](https://go.bitdoze.com/vultr) offer scalable resources starting at a few euros per month. A 2 vCPU / 4 GB RAM VPS (e.g. Hetzner CX22) is enough for most teams under 10 users. Plan 4 GB+ if running NocoDB or Teable with PostgreSQL. If you want a web UI to manage your Docker deployments, look at [Dokploy for one-click Docker deploys](https://www.bitdoze.com/dokploy-install/) or a [self-hosted PaaS like Coolify](https://www.bitdoze.com/coolify-install-heroku-alternative/). For managing multiple servers, check the [self-hosted server panels](https://www.bitdoze.com/best-self-hosted-panels/) comparison. > To monitor CPU, memory, and disk on your VPS: [How to monitor server and Docker resources](https://www.bitdoze.com/sever-monitoring/) ### Home server For complete hardware control with a one-time cost, a home server works well for personal or small-team use. #### Mini PC Mini PCs are compact, energy-efficient, and powerful enough for all the tools in this article. Expect to pay €200–400 for a capable unit. An [ASUS DC510 mini PC](https://go.bitdoze.com/asus-dc510) or similar Intel NUC-style device handles Docker workloads fine. For buying guidance, see [best mini PCs for home servers](https://www.bitdoze.com/best-mini-pc-home-server/) and [Docker containers for home servers](https://www.bitdoze.com/docker-containers-home-server/). #### NAS (Network Attached Storage) NAS devices from Synology, QNAP, and Asustor can run Docker containers. Good for storage-heavy workloads but limited CPU. Fine for personal use, marginal for teams with concurrent access. ## Quick comparison: all tools at a glance | Application | License | GitHub Stars | Complexity | Backend | Key Benefit | OSS? | |---|---|---|---|---|---|---| | NocoDB | Sustainable Use License | 64.4k | Medium | MySQL/PG/SQLite/MSSQL/MariaDB | Most Airtable-like UI, widest DB support | source-available | | Teable | AGPL-3.0 (CE) | 21.6k | Medium | PostgreSQL | Closest Airtable clone, million-row | CE: yes | | Baserow | MIT (core) | 5.5k | Medium | PostgreSQL | Best UX, AI assistant, Automations | core: yes | | Grist | Apache 2.0 | 11.4k | Low-Med | SQLite | Python formulas, spreadsheet-native | yes | | undb | AGPL-3.0 | 3.0k | Low | SQLite/PostgreSQL | Lightweight, private-first | yes | | Mathesar | GPL-3.0 | 5.1k | Medium | PostgreSQL | Works on existing PG schemas | yes | ## Top self-hosted Airtable alternatives If you are interested in more free self-hosted apps, check [toolhunt.net self hosted section](https://toolhunt.net/sh/). ### NocoDB: most feature-rich (source-available) ![nocodb ui](../../assets/images/24/11/nocodb.png) [NocoDB](https://nocodb.com/) transforms any MySQL, PostgreSQL, SQLite, Microsoft SQL Server, or MariaDB into a spreadsheet-like interface. It has 64.4k GitHub stars and the most Airtable-like UI of any tool in this list. NocoDB changed from AGPL-3.0 to a Sustainable Use License (Fair Code) in early 2026. It is no longer open source. You can still self-host for free, but offering NocoDB as a paid service or redistributing it commercially requires a separate license. Many advanced features are now gated behind paid tiers. Community Edition features (free): - Grid, Gallery, Kanban, Form views - REST and GraphQL APIs - Webhooks - Role-based access control - Canvas Grid (spreadsheet-like) Enterprise-only features (paid): - Realtime Collaboration - Dashboard Widgets (Bar, Line, iFrame, Markdown) - Gantt View, Timeline View - Calendar Sync (Google/Outlook/CalDAV) - Interfaces (app builder) - NocoDB Sync, Custom Sync - White-Label, Oracle/SQL Server support **Deploy with Docker:** ```bash docker run -d --name nocodb \ -p 8080:8080 \ -e NC_DB="pg://host:5432?u=user&p=password&d=nocodb" \ -e NC_AUTH_JWT_SECRET="your-secret" \ nocodb/nocodb:latest ``` SQLite works for quick evaluation, but PostgreSQL is recommended for production. Set `NC_SITE_URL` for shared links and OAuth to work. NocoDB 2026.05.2+ enforces SSRF protection by default. If connecting to local/private databases, set `NC_ALLOW_LOCAL_EXTERNAL_DBS=true`. **Verify:** `curl http://localhost:8080` should return the NocoDB login page. For more details, visit the [NocoDB GitHub repository](https://github.com/nocodb/nocodb). ### Teable: closest Airtable clone (open source) Teable has more GitHub stars (21.6k) than Baserow and Grist combined. It's the closest visual clone to Airtable among genuinely open-source options, filling the gap left by NocoDB's license change. [Teable](https://teable.ai/) is PostgreSQL-native (Next.js + NestJS) and looks almost identical to Airtable. If your team evaluated NocoDB but licensing is a dealbreaker, Teable is worth a look. Key features: - Grid, Form, Kanban, Gallery, Calendar views - Real-time collaboration - Million-row scalability (Postgres-backed) - AI fields and formula generation - SQL query mode for developers - Chart visualization - Comments, history, undo/redo - Plugin system Enterprise features (advanced AI, automation, authority matrix) require a paid license, but the Community Edition covers core Airtable functionality: views, collaboration, fields, and APIs. **Deploy with Docker:** ```bash git clone https://github.com/teableio/teable.git cd teable/dockers/examples/standalone/ docker compose up -d ``` **Verify:** `curl http://localhost:8080` should return the Teable login/registration page. **Failure mode:** Teable requires PostgreSQL. The compose file handles this, but if you bring your own Postgres, ensure the `TEABLE_PG_DATABASE_URL` env var is set correctly. The container will crash-loop without it. ### Baserow: best UX with AI assistant ![baserow ui](../../assets/images/24/11/baserow.webp) [Baserow](https://baserow.io/) has an MIT-licensed core (5.5k GitHub stars) and focuses on the best non-technical user experience. It migrated from GitLab to GitHub in late 2025. Baserow 2.0 (late 2025) added a lot: - **Kuma AI Assistant**: build tables, write formulas, configure automations via natural language. Self-hosted users can bring their own model/API key. - **Automations Builder (beta)**: triggers, actions, router nodes, conditions, formulas, variables. AI steps inside automations. - **AI field upgrades**: bulk-generate columns, auto-refresh values, multiple AI model support - **Timeline view** with date dependencies (Gantt-style) - **Two-factor authentication (2FA)** - **Workspace-wide search** - **Two-way PostgreSQL sync** - **Dashboards** with summaries, bar charts, pie/doughnut charts - **Application Builder improvements**: theme templates, custom CSS/JS, Send Email and HTTP Request actions The unlicensed self-hosted version has unlimited rows, storage, and API requests, but lacks Kanban, Calendar, and Survey views. Premium features require a license. Baserow's Automations Builder handles simple workflows (triggers, conditions, actions). For complex multi-step automations across multiple services, pair it with a dedicated automation platform. See [how to self-host n8n for advanced automations](https://www.bitdoze.com/n8n-self-host-workflow-automation/). **Deploy with Docker:** ```bash docker run -d --name baserow \ -p 80:80 \ -v baserow_data:/baserow/data \ -e BASEROW_PUBLIC_URL=https://baserow.example.com \ baserow/baserow:latest ``` Set `BASEROW_PUBLIC_URL`. Without it, features like file uploads and shared links break. **Verify:** `curl http://localhost:80` should return the Baserow login page. **Failure mode:** If you see CSRF errors on login, `BASEROW_PUBLIC_URL` is missing or mismatched. For the full setup guide, visit the [Baserow documentation](https://baserow.io/docs/installation/install-with-docker). ### Grist: spreadsheet-native with Python scripting ![grist ui](../../assets/images/24/11/grist.png) [Grist](https://www.getgrist.com/) is Apache 2.0 licensed (11.2k stars), truly open source. It's a spreadsheet-database hybrid where formulas are written in Python, not a proprietary formula language. If your team thinks in pandas and NumPy, Grist is the obvious pick. Recent additions: - **AI Formula Assistant**: supports OpenRouter (Claude, DeepSeek, Mistral, etc.), not just OpenAI - **Grist Assistant** (full edition): AI help with building tables, dashboards, styling, access rules - **`grist-oss` Docker image**: pure Apache 2.0, no proprietary code at all - **`grist-desktop`**: native desktop app for Linux/macOS/Windows - **`grist-static`**: fully in-browser build for static websites - **SCIM support** for user/group provisioning - **Service accounts** for fine-grained API access Grist offers two Docker images: `gristlabs/grist` (default, includes inert proprietary code) and `gristlabs/grist-oss` (pure Apache 2.0). For maximum open-source purity, use `grist-oss`. **Deploy with Docker:** ```bash docker run -d --name grist \ -p 8484:8484 \ -v grist-data:/persist \ gristlabs/grist ``` **Verify:** `curl http://localhost:8484` should return the Grist welcome page. **Production note:** For production, set `GRIST_SANDBOX_FLAVOR=gvisor` (Linux) to sandbox Python formula execution. Without this, formulas run in the host environment. Fine for evaluation, not for production. **Pricing:** Free self-hosted full edition for individuals and orgs with less than US $1M in total annual funding. For detailed setup, visit the [Grist documentation](https://support.getgrist.com/self-managed/). ### undb: lightweight and private-first ![undb ui](../../assets/images/24/11/undb.png) [undb](https://undb.io/) is AGPL-3.0 (3.0k stars) and focuses on being lightweight. It supports both SQLite and PostgreSQL backends, has a clean minimalist interface with Table and Kanban views, and runs on minimal resources. undb's last GitHub push was July 2025. The project is still functional, but consider this when evaluating long-term support and maintenance. **Deploy with Docker:** ```bash docker run -d -p 3721:3721 ghcr.io/undb-io/undb ``` **Verify:** `curl http://localhost:3721` should return the undb interface. undb is a good choice for personal use, small teams, or situations where you want a simple database UI without the overhead of PostgreSQL. For teams evaluating long-term viability, Teable or Grist have stronger community momentum. ### Mathesar: honorable mention (Postgres-native) [Mathesar](https://mathesar.org/) is GPL-3.0 (5.1k stars), built with Python/Django + Svelte, and takes a different approach: it works directly on your existing PostgreSQL schemas. No abstraction layer, no migration needed. It respects your existing Postgres tables and access controls. Key differentiators: - Works directly on your Postgres database, no migration needed - Respects existing Postgres access control - 100% open source, no premium features, no paywalls - Good for teams that already have Postgres and want a UI on top Limitations: Postgres-only, smaller community, less polished UI than NocoDB or Teable. **Deploy with Docker:** ```bash docker run -d --name mathesar \ -p 8000:8000 \ -e DJANGO_DATABASE_URL=postgres://user:password@host:5432/dbname \ mathesar/mathesar-prod:latest ``` **Verify:** `curl http://localhost:8000` should return the Mathesar interface. Mathesar is best positioned for teams already running PostgreSQL who want a spreadsheet-like UI without touching their existing schema. ## Licensing and open source status comparison This is the most important section in this 2026 update. Licensing has changed a lot, especially for NocoDB. "Open source" has a specific meaning: an [OSI-approved license](https://opensource.org/licenses) (Apache 2.0, MIT, GPL, AGPL). "Source-available" or "Fair Code" licenses allow viewing and self-hosting but restrict commercial redistribution. | Tool | License | Fully Open Source? | Free Self-Host? | Paid Tiers | |---|---|---|---|---| | NocoDB | Sustainable Use License | no | yes | Enterprise features gated | | Teable | AGPL-3.0 (CE) | CE: yes | yes | Enterprise features | | Baserow | MIT (core) | core: yes | yes | Premium/Advanced/Enterprise | | Grist | Apache 2.0 | yes | yes | Free for <$1M orgs | | undb | AGPL-3.0 | yes | yes | None currently | | Mathesar | GPL-3.0 | yes | yes | None | OSI-approved licenses (Apache 2.0, MIT, GPL, AGPL) meet the Open Source Definition. "Source-available" or "Fair Code" licenses like NocoDB's allow viewing and self-hosting but restrict commercial redistribution. If true open-source licensing matters to your team, Grist, undb, and Mathesar are the safest choices. **Why this matters for self-hosters:** If you plan to offer the tool as a service, redistribute it, or embed it in a product, licensing is critical. NocoDB's Sustainable Use License prohibits commercial redistribution. Teable's AGPL requires you to open-source modifications if you distribute. Grist's Apache 2.0 and Baserow's MIT core are the most permissive. ## Airtable pricing vs self-hosted costs The math here is straightforward. **Airtable 2026 pricing:** - Team: $20/user/mo (annual) or $24 (monthly) - Business: $45/user/mo (annual) or $54 (monthly) - 10-person team on Business = **$5,400/year** - 50-person team on Business = **$27,000/year** **Self-hosted cost:** - [Hetzner](https://go.bitdoze.com/hetzner) CX22 (2 vCPU, 4 GB RAM): €4.49/month (€54/year) - [Hostinger](https://go.bitdoze.com/hostinger-vps) VPS: starting ~€5/month - [DigitalOcean](https://go.bitdoze.com/do) Basic Droplet: $6/month - [Vultr](https://go.bitdoze.com/vultr) Cloud Compute: $6/month A 10-person team on Airtable Business pays $5,400/year. A Hetzner CX22 VPS costs €54/year. Self-hosting any of these tools on that VPS gives you comparable functionality at ~1% of the cost. The caveat: self-hosting cost doesn't include your time for maintenance, updates, and backups. But if you're already running Docker containers, the marginal effort is small. ## Operator notes: database backends, backups, and resource planning ### Database backend comparison The database backend determines resource requirements, backup strategy, and scalability ceiling: - **PostgreSQL-only:** Teable, Baserow, Mathesar: more robust for concurrent access, requires more RAM - **Multi-DB:** NocoDB: supports MySQL, PostgreSQL, SQLite, MSSQL, MariaDB. PostgreSQL recommended for production - **SQLite-based:** Grist (SQLite by default), undb (SQLite or PostgreSQL option): simpler setup, single-writer limitation PostgreSQL handles concurrent users and large datasets better. SQLite is simpler to back up and runs on fewer resources. For teams under 10 users with <100k rows, either works fine. ### Backup strategies For SQLite-based tools (Grist, undb with SQLite): ```bash # Stop the container, copy the data volume, restart docker stop grist cp -r /var/lib/docker/volumes/grist-data/_data /backup/grist-$(date +%F) docker start grist ``` For PostgreSQL-based tools (Teable, Baserow, Mathesar, NocoDB with PG): ```bash docker exec postgres_container pg_dump -U user dbname > backup-$(date +%F).sql ``` A backup you haven't tested is not a backup. After your first backup, restore it to a fresh container and verify the data is intact. Schedule daily backups. Store them off-site (S3-compatible storage). Test restores quarterly at minimum. ### Resource planning Minimum VPS specs per tool for a small team (<10 users, <100k rows): | Tool | Minimum RAM | Recommended | |---|---|---| | NocoDB (with PG) | 4 GB | 4 GB | | Teable | 4 GB | 4 GB | | Baserow | 4 GB | 4 GB | | Grist | 2 GB | 4 GB | | undb | 2 GB | 2 GB | | Mathesar | 4 GB | 4 GB | Monitor CPU and memory once deployed. [How to monitor server and Docker resources](https://www.bitdoze.com/sever-monitoring/). ## Factors to consider when choosing an alternative When choosing a tool, think about what matters most for your setup: 1. **Ease of use and UI polish**: Teable and Baserow have the most polished interfaces. NocoDB is close. Grist has a learning curve if you're not comfortable with Python formulas. 2. **Scalability and performance**: PostgreSQL-backed tools (Teable, Baserow, Mathesar) handle concurrent access and large datasets better. SQLite tools (Grist, undb) are simpler but single-writer. 3. **Integration capabilities**: All tools offer REST APIs. NocoDB also has GraphQL. None match Airtable's automation depth natively. For complex workflows, pair your database tool with [self-hosted n8n for advanced automations](https://www.bitdoze.com/n8n-self-host-workflow-automation/). 4. **Community support and development activity**: NocoDB (64.4k stars) and Teable (21.6k) have the most active communities. Check GitHub issue activity and release cadence before committing. 5. **Licensing and long-term viability**: NocoDB's license change is a warning: projects can change terms. True OSI-approved licenses (Grist, undb, Mathesar) offer more predictability. **Need widest DB support and most features?** → NocoDB (but accept the Fair Code license) **Need closest Airtable clone with OSS license?** → Teable **Need best non-technical UX + AI assistant?** → Baserow **Need spreadsheet-native with Python formulas?** → Grist **Need lightweight / personal use?** → undb **Need Postgres-native on existing DB?** → Mathesar ## Security considerations for self-hosted containers When deploying these containers in production: - **Reverse proxy with SSL**: don't expose raw HTTP ports. Use [Traefik](https://www.bitdoze.com/traefik-proxy-docker/) or Nginx Proxy Manager to front these services with HTTPS and automatic certificate renewal. - **Regular container updates**: watch for security releases. Set up Watchtower or similar for automated updates, or at minimum check monthly. - **Network segregation**: run database containers on an internal Docker network, not exposed to the host. - **Access control and MFA**: enable 2FA where available (Baserow supports it). Use strong JWT secrets. - **Monitoring and logging**: set up basic monitoring. [Secure your VPS with CrowdSec](https://www.bitdoze.com/crowdsec-secure-server/) for intrusion detection. - **DNS-level protection**: use [NextDNS](https://go.bitdoze.com/nextdns) for DNS-level privacy and ad/malware blocking on your server. - **SSRF protection**: NocoDB 2026.05.2+ enforces SSRF protection by default. If you need to connect to local/private databases, set `NC_ALLOW_LOCAL_EXTERNAL_DBS=true`. ## Conclusion The self-hosted Airtable space changed a lot since 2025. NocoDB is still the most feature-rich option but is no longer open source. Teable emerged as the closest Airtable clone with a genuine AGPL license. Baserow 2.0 added AI and automations. Grist remains the best choice for teams that think in Python. undb is the lightweight option. Mathesar fills a niche for Postgres-native teams. The cost math is clear: self-hosting on a €5/month VPS gives you 90% of Airtable's functionality at 1% of the price. The tradeoff is you own the operations: backups, updates, security. If you're already running Docker, that's a trade worth making. Start with Docker on a cheap VPS. Evaluate one or two tools with real data before committing. The migration path from Airtable is CSV export → import, with some manual cleanup of linked records.

How to Monitor Server & Docker Resources: CPU, Memory, Disk

Sat, 08 Aug 2026 00:00:00 GMT

import Button from "../../components/widgets/Button.astro"; import Notice from "../../components/widgets/Notice.astro"; import ListCheck from "../../components/widgets/ListCheck.astro"; import Accordion from "../../components/widgets/Accordion.astro"; import Tabs from "../../components/widgets/Tabs.astro"; import Tab from "../../components/widgets/Tab.astro"; import YouTubeEmbed from "../../components/widgets/YouTubeEmbed.astro"; If you run Docker on a VPS, you need to know when CPU spikes, disk fills, or a container dies, before your users notice. Server monitoring is the systematic process of tracking resource utilization, container health, and service availability so you can catch problems early. This guide compares four free, self-hosted monitoring tools (Beszel, Netdata, Dozzle, and Prometheus/Grafana), adds Uptime Kuma for availability checks, and gives you a clear default stack for 1–20 servers. Whether you're running [Docker containers for your home server](/docker-containers-home-server/) or managing production workloads on cheap VPS boxes, the monitoring stack you choose matters. ## Quick picks: which monitoring tool should you use? For 90% of self-hosters with 1–20 servers, deploy **Beszel** (metrics) + **Dozzle** (logs) + **Uptime Kuma** (availability). Total RAM overhead: ~50–80 MB. You can have the whole stack running tonight. If you need per-second resolution and AI anomaly detection, go with **Netdata**, but budget 200-500 MB RAM. If you're running an organization with 50+ targets and custom PromQL dashboards, use **Prometheus + Grafana**, but budget 1 GB+ RAM and a weekend for setup. **You need Beszel if you want:** - A monitoring dashboard that runs in 5 minutes with ~10–25 MB RAM - Built-in Docker container stats, GPU monitoring, and S.M.A.R.T. disk health - OAuth/OIDC login and automatic S3 backups **You need Netdata if you want:** - Per-second metric collection with 800+ integrations - AI-powered anomaly detection and blast radius analysis - Deep production debugging at 3 am **You need Prometheus + Grafana if you want:** - Custom PromQL dashboards and long-term metric storage - Enterprise-grade alerting with Alertmanager - Multi-team observability with role-based access Here's what each tool actually costs you in RAM on a VPS: | Tool | RAM (idle) | Best for | |---|---|---| | Beszel agent | ~10–15 MB | Every server | | Beszel hub | ~12 MB | Central dashboard | | Dozzle | ~10–18 MB | Log viewing + alerts | | Uptime Kuma | ~30–50 MB | HTTP/TCP availability | | Netdata | 200–500 MB | Deep metrics, AI | | Prometheus + Grafana | 500 MB–1 GB+ | Enterprise observability | Compare these numbers against [self-hosted server management panels](/best-self-hosted-panels/) to plan your total resource budget. ## Key areas in server monitoring Effective server monitoring tracks four resource domains. The tools in this article cover all of them. | Metric Type | Traditional Server | Container Environment | Cloud Infrastructure | |---|---|---|---| | CPU | Overall usage | Per container usage | Instance utilization | | Memory | Physical/Swap | Container limits | Instance limits | | Storage | Partition usage | Volume usage | Block storage | | Network | Interface stats | Container networks | VPC metrics | Before you deploy anything, it helps to [benchmark your cloud server](/benchmark-cloud-servers/) so you know your baseline. ### CPU monitoring - Load averages (1, 5, 15 minute) - Per-core utilization - Process-level CPU consumption - System/user time split For a deeper dive on CPU alerting, see how to [monitor CPU usage with alerts](/monitor-cpu-usage-and-send-email-alerts-in-linux/). ### Memory monitoring - Available RAM and swap usage - Buffer/cache utilization - Per-process memory consumption - OOM kill events (Dozzle can alert on these) ### Disk & filesystem monitoring - Disk space usage (percentage and absolute) - Inode utilization - Read/write operations and I/O wait times - S.M.A.R.T. disk health with failure alerts (Beszel v0.17+) Disk fills up fast with Docker images and logs. If you're running low, [clean up Docker disk usage](/clean-docker-overlay2-dir/) to reclaim space. ### Network monitoring - Bandwidth utilization per interface - Packet loss and latency - Connection states and socket counts - Container-level network stats ## Importance of getting notified Proactive alerting is the difference between catching a problem at 90% disk and waking up to a dead server at 100%. Every tool in this article supports notifications: - **Beszel**: ntfy, email, webhook, Telegram, Gotify - **Netdata**: 90+ notification channels including Slack, Discord, PagerDuty - **Dozzle**: webhook delivery to Slack, Discord, ntfy, or custom endpoints - **Prometheus**: Alertmanager with multi-channel routing The key principles still apply: 1. **Early warning.** Detect issues before they become critical. Monitor trend changes, not just thresholds. 2. **Quick response.** Deliver notifications with diagnostic info and clear action items. 3. **Prevent alert fatigue.** Use intelligent thresholds, correlation, and proper priorities. If everything is critical, nothing is. Instead of wiring each monitoring tool to email separately, route all alerts through a single notification server like [ntfy](https://ntfy.sh/) or [Gotify](https://gotify.net/). Every tool in this article supports webhook delivery. Point them all at one endpoint, then manage subscriptions from a single place. One webhook target to maintain, one place to mute at 3 am. ## Metrics monitoring: track CPU, memory, disk & network This section covers tools that watch system resources. Metrics tell you *what* is happening (CPU at 95%, memory exhausted, disk filling up). The log monitoring section below covers *why* it's happening (error messages, stack traces, crash loops). ### Beszel: lightweight server & Docker monitoring Beszel is the recommended starting point for most readers. It uses ~10-25 MB total RAM, deploys in 5 minutes, and now includes GPU monitoring, S.M.A.R.T. disk health, systemd service monitoring, and OAuth/OIDC. Version 0.18.7, 22,700+ GitHub stars, MIT license. [Beszel](https://github.com/henrygd/beszel) is a lightweight monitoring hub with agents that report back via SSH or universal tokens. It's designed for small to medium fleets, the kind of setup where you have 1-20 VPS boxes and want a clean dashboard without the overhead of Netdata or Prometheus. Main Beszel interface: ![Beszel hub dashboard showing CPU, memory, disk, and network metrics for multiple servers](../../assets/images/24/11/beszel1.jpeg) Beszel graphs: ![Beszel system detail view with per-core CPU graphs, memory utilization, and Docker container stats](../../assets/images/24/11/beszel2.jpeg) #### Beszel key features (v0.18) What's new since the original article: - **Universal tokens** (v0.12+). Create a token at `/settings/tokens` and skip per-system key setup. This simplifies multi-server deployment significantly. - **OAuth2/OIDC.** Sign in via Google, GitHub, Authentik, Authelia. Password auth can be disabled entirely. - **S.M.A.R.T. disk monitoring** with failure alerts. Catch a dying drive before it takes your data. - **GPU monitoring.** NVIDIA (NVML/nvtop), AMD, Intel, experimental Apple Silicon. - **systemd service monitoring.** See which services are running and get alerted on failures. - **Automatic backups** to disk or S3-compatible storage. - **Multi-user** with admin and read-only roles. Since v0.12.0, universal tokens are the recommended auth method. You create a token in the hub UI and paste it into the agent config. No SSH key juggling. ```yaml services: beszel-agent: image: henrygd/beszel-agent:latest container_name: beszel-agent restart: unless-stopped network_mode: host volumes: - /var/run/docker.sock:/var/run/docker.sock:ro environment: PORT: 45876 TOKEN: "your-universal-token-from-hub" ``` The original SSH key-based auth still works. Generate an ed25519 key pair, paste the public key in the hub, and the private key in the agent config. ```yaml services: beszel-agent: image: henrygd/beszel-agent:latest container_name: beszel-agent restart: unless-stopped network_mode: host volumes: - /var/run/docker.sock:/var/run/docker.sock:ro environment: PORT: 45876 KEY: "ssh-ed25519 AAAAC3..." ``` #### Deploy Beszel hub with Docker Compose ```yaml services: beszel: image: henrygd/beszel:latest container_name: beszel restart: unless-stopped environment: APP_URL: http://localhost:8090 # change to your domain in production ports: - 8090:8090 volumes: - ./beszel_data:/beszel_data ``` Save this as `docker-compose.yml`, then: ```bash mkdir -p beszel && cd beszel # paste the compose file above docker compose up -d ``` **Verify:** Open `http://your-ip:8090`. The setup wizard should appear. Create your admin account. If you get a blank page, check that `APP_URL` matches your access URL. If your only server goes down, your monitoring goes down with it. Beszel hub uses ~12 MB RAM — cheap enough to run on a separate [Hetzner VPS](https://go.bitdoze.com/hetzner) (CX22 at ~€4/month) or a [Hostinger VPS](https://go.bitdoze.com/hostinger-vps). Even a Raspberry Pi works. The agent stays on your production servers; the hub lives elsewhere. #### Deploy Beszel agent with Docker Compose On each monitored server: ```yaml services: beszel-agent: image: henrygd/beszel-agent:latest container_name: beszel-agent restart: unless-stopped network_mode: host volumes: - /var/run/docker.sock:/var/run/docker.sock:ro # monitor other disks/partitions by mounting into /extra-filesystems # - /mnt/disk/.beszel:/extra-filesystems/sda1:ro environment: PORT: 45876 TOKEN: "your-universal-token-from-hub" ``` To get your token: in the Beszel hub UI, go to **Settings → Tokens**, create a new universal token, and paste it into the agent's `TOKEN` environment variable. **Verify:** The system row should flip green in the hub UI within 30 seconds. If red, check `docker logs beszel-agent` for connection errors. **Wrong TOKEN or KEY:** Regenerate the token in the hub and update the agent compose. Restart the agent. **Firewall blocking port 45876:** The hub connects to the agent on port 45876. Make sure your firewall allows inbound TCP on that port from the hub's IP: ```bash sudo ufw allow from HUB_IP to any port 45876 ``` **Agent not running:** Check `docker ps | grep beszel-agent`. If it's not listed, check `docker logs beszel-agent` for startup errors. **Docker socket permissions:** Ensure `/var/run/docker.sock` is readable. The `:ro` mount is sufficient — the agent only reads stats, it doesn't control containers. **APP_URL mismatch:** The `APP_URL` env var must match how you access the hub. If you're using `http://localhost:8090` but accessing via a reverse proxy domain, update `APP_URL` to the domain. **Port not exposed:** Verify with `docker port beszel` that 8090 is mapped. **Reverse proxy misconfiguration:** If behind Caddy/Nginx/Traefik, ensure the proxy passes the `Host` header and forwards to port 8090. **Ops notes:** - **Backup:** The `/beszel_data` directory contains all configuration and history. Back it up, or configure S3 backup in hub settings. - **Updates:** `docker compose pull && docker compose up -d` — Beszel hub and agent update independently. - See how to [pair Beszel with Uptime Kuma](/beszel-uptime-kuma/) for the complete setup with Dokploy. ### Netdata: deep real-time server monitoring [Netdata](https://www.netdata.cloud/) gives you 2,000+ metrics at 1-second resolution with AI anomaly detection. That depth costs 200–500 MB of RAM. For "is my CPU OK," that's overkill. For debugging a production incident at 3 am with per-second granularity, it's worth every megabyte. Version 2.10.4 (July 2026), 79,600+ GitHub stars, GPL-3.0+. ![Netdata real-time dashboard with per-second CPU, memory, disk I/O, and network metrics](../../assets/images/24/11/netdata1.jpeg) #### Netdata key features (v2.10) - **800+ integrations** with auto-detection — Netdata discovers what's running and starts collecting metrics with zero config. - **AI Co-Engineer** — built-in AI chat, AI reporting, and blast radius detection. The agent has self-learning anomaly detection built in. - **Per-second metric collection** — no other free tool matches this granularity. - **Parent streaming + HA clustering** — scale to thousands of nodes with parent-child architecture. - **UI-based alert configuration** — define alerts in the Cloud dashboard, not just config files. Includes alert silencing, recurrence rules, and acknowledgement. #### Netdata pricing: Community vs Homelab vs Business The old "Community vs Cloud" split is gone. Current tiers (Aug 2026): | Plan | Price | Nodes | Custom Dashboards | Retention | |---|---|---|---|---| | Community | Free | 5 | 1 | 3 GB disk, >1 year | | Homelab | $90/yr | Unlimited | Unlimited | Fair usage | | Business | $4.50/node/mo | Unlimited | Unlimited | Full | | Enterprise On-Premise | Contact sales | Unlimited | Unlimited | Full | If you have more than 5 servers, the **Homelab plan at $90/year** is the sweet spot. Unlimited nodes with fair usage — this is the tier designed for self-hosters. The free Community plan (5 nodes, 1 custom dashboard, 3 GB disk / >1 year retention) is enough to evaluate. Compare: SaaS alternatives like Datadog charge $15–18/host/month. Self-hosting Netdata is free; the Cloud plan adds multi-node dashboards and AI features. #### Deploy Netdata with Docker ```yaml services: netdata: image: netdata/netdata:stable container_name: netdata restart: unless-stopped pid: host network_mode: host cap_add: - SYS_PTRACE - SYS_ADMIN security_opt: - apparmor:unconfined volumes: - netdataconfig:/etc/netdata - netdatalib:/var/lib/netdata - netdatacache:/var/cache/netdata - /etc/passwd:/host/etc/passwd:ro - /etc/group:/host/etc/group:ro - /etc/localtime:/etc/localtime:ro - /proc:/host/proc:ro - /sys:/host/sys:ro - /var/run/docker.sock:/var/run/docker.sock:ro environment: - NETDATA_CLAIM_TOKEN=your-cloud-token # optional: connect to Netdata Cloud volumes: netdataconfig: netdatalib: netdatacache: ``` **Verify:** Access `http://your-ip:19999` — the dashboard should populate with live metrics within seconds. If you see an empty page, check the Docker socket mount and network mode. **Token mismatch:** Regenerate the claim token from Netdata Cloud and update the `NETDATA_CLAIM_TOKEN` env var. **Network egress blocked:** Netdata Cloud requires outbound HTTPS to `app.netdata.cloud`. Check your firewall rules. **Firewall:** If you're not using Cloud, just access the agent directly at port 19999 — no outbound connection needed. On a 1 GB VPS, Netdata alone can take 200–500 MB — that's 20–50% of your total RAM. Verify with `docker stats` before committing. To reduce memory: - Disable unused collectors in `/etc/netdata/netdata.conf` - Reduce metric retention periods - If you don't need per-second resolution, consider switching to Beszel (~10–15 MB) **Ops notes:** - On a 1 GB VPS, Netdata alone takes 20–50% of RAM — verify with `docker stats` before committing alongside other services. - **Backup:** `/etc/netdata` for configs, `/var/cache/netdata` for historical data. - **Updates:** `docker compose pull && docker compose up -d` ### Prometheus & Grafana: enterprise server monitoring The full Prometheus + Grafana stack needs 500 MB–1 GB+ RAM. Don't run this on a 1 GB VPS alongside your applications. This is for dedicated monitoring nodes or organizations with real infrastructure budgets. Prometheus handles metrics collection and storage. Grafana provides visualization and alerting. Together they're the industry standard for enterprise monitoring — PromQL for queries, Alertmanager for routing, and custom dashboards for everything. Prometheus 3.x (Nov 2024) and Grafana 12.x (May 2025) are the current releases. ![Grafana 12 dashboard with Prometheus 3.x metrics showing server CPU, memory, and container resource usage](../../assets/images/24/11/prometheus_grafana.webp) #### Prometheus/Grafana key features (Prometheus 3.x, Grafana 12.x) **Prometheus 3.0 changes:** - Native OTLP ingestion on `/api/v1/otlp/v1/metrics` — receive OpenTelemetry metrics directly without a collector. - Remote Write 2.0 with improved compression. - UTF-8 support in label values. - New web UI. **Grafana 12 changes:** - Observability as code — Git Sync for dashboards. - Dynamic dashboards with drilldown apps. - Grafana Alloy as the modern single collector (replaces node_exporter + cAdvisor + Promtail). **Prometheus capabilities:** - Pull-based metrics collection with service discovery - PromQL query language for complex aggregations - Time-series database with efficient compression - Customizable retention periods **Grafana strengths:** - Customizable dashboards with template variables - Multiple data source support (Prometheus, Loki, InfluxDB, etc.) - Multi-channel alerting with grouping and escalation #### Deployment overview The essential components: Prometheus for metrics, Grafana for visualization, Node Exporter for system metrics, and cAdvisor for container stats. For a Docker-based setup: ```yaml services: prometheus: image: prom/prometheus:v3.13.0 container_name: prometheus restart: unless-stopped volumes: - ./prometheus.yml:/etc/prometheus/prometheus.yml - prometheus_data:/prometheus ports: - 9090:9090 grafana: image: grafana/grafana:12.0.0 container_name: grafana restart: unless-stopped ports: - 3000:3000 volumes: - grafana_data:/var/lib/grafana node-exporter: image: prom/node-exporter:latest container_name: node-exporter restart: unless-stopped pid: host volumes: - /proc:/host/proc:ro - /sys:/host/sys:ro - /:/rootfs:ro cadvisor: image: gcr.io/cadvisor/cadvisor:latest container_name: cadvisor restart: unless-stopped volumes: - /:/rootfs:ro - /var/run/docker.sock:/var/run/docker.sock:ro - /sys:/sys:ro - /var/lib/docker:/var/lib/docker:ro volumes: prometheus_data: grafana_data: ``` For production, there are also Kubernetes Helm charts, Ansible automation, and managed solutions like AWS Managed Grafana or Google Cloud Managed Prometheus. The official docs cover these in detail: [Prometheus Installation](https://prometheus.io/docs/prometheus/latest/installation/) and [Grafana Installation](https://grafana.com/docs/grafana/latest/setup-grafana/installation/). **Ops notes:** - **Backup:** The Prometheus TSDB data directory, `prometheus.yml`, and Grafana dashboards (export as JSON). - **Cost:** Grafana Cloud free tier gives you 10k series with 14-day retention. Pro: $19/month + $6.50/1k series after 10k. Self-hosting is free but costs you RAM. - Check your [Docker firewall configuration](/docker-bypasses-firewall/) — Prometheus pulls metrics from exporters, so the network path matters. ## Log monitoring: track Docker container logs Metrics tell you *what* is happening. Logs tell you *why*. When CPU spikes, you need to know which process is responsible. When a container crashes, you need the error message. This is where Dozzle comes in — it pairs with Beszel or Netdata for metrics to give you the complete picture. ### Dozzle: Docker log viewer with alerts [Dozzle](https://dozzle.dev/) started as a lightweight log viewer. Since v10 (Feb 2026), it's grown into a full Docker operations tool with alerts, SQL analytics, container actions, and shell access. Version 10.6.15, 14,000+ GitHub stars, MIT license. Image size: ~7–10 MB. ![Dozzle v10 Docker log viewer showing real-time container log streams with search and filter](../../assets/images/24/11/dozzle1.png) #### Dozzle key features (v10) What's new since the original article: - **Alerts & webhooks** — log pattern matching ("alert when any container logs contain 'FATAL'"), CPU/memory metric thresholds ("alert when postgres exceeds 85% memory"), and container lifecycle events ("alert when any container gets OOM-killed"). Delivers to Slack, Discord, ntfy, or custom endpoints. - **DuckDB SQL analytics** — query your live log streams with SQL in the browser. Example: `SELECT * FROM logs WHERE message LIKE '%Error%'`. Useful for debugging patterns across containers. - **Container actions** — stop, start, and restart containers from the browser. Disabled by default. - **Shell access** — exec into containers from the browser. Disabled by default. - **Built-in authentication** — file-based auth (`DOZZLE_AUTH_PROVIDER=simple`) and forward proxy auth (Authelia). - **Kubernetes support** and multi-host agents with TLS. - Command palette (Cmd+K), theme-aware ANSI colors. Dozzle sends anonymous usage analytics by default. Opt out with `DOZZLE_NO_ANALYTICS=true` in your compose environment. This is for usage telemetry only — it does not affect the DuckDB analytics feature. #### Deploy Dozzle with Docker Compose ```yaml services: dozzle: image: amir20/dozzle:latest container_name: dozzle restart: unless-stopped volumes: - /var/run/docker.sock:/var/run/docker.sock - ./dozzle_data:/data # required: persists alert/notification configs ports: - 8080:8080 environment: DOZZLE_NO_ANALYTICS: "true" # opt out of anonymous analytics # DOZZLE_AUTH_PROVIDER: simple # enable built-in file-based auth # DOZZLE_ENABLE_ACTIONS: true # stop/start/restart containers from UI # DOZZLE_ENABLE_SHELL: true # exec into containers from UI ``` **Verify:** Navigate to `http://your-ip:8080` — you should see your running containers listed in the sidebar. Click one to see live log streaming. If the list is empty, verify the Docker socket mount. **Important:** The `/data` volume mount is **required** as of v10. Without it, your alert configurations and notification settings are lost on every container restart. **Docker socket permissions:** Ensure `/var/run/docker.sock` is readable by the container user. The default Docker socket permissions (root:docker, mode 660) usually work, but some distros restrict this. **SELinux/AppArmor:** On SELinux-enforced systems, you may need `:z` on the socket mount: ```yaml volumes: - /var/run/docker.sock:/var/run/docker.sock:z ``` **Wrong socket path:** On some systems (Docker rootless, Podman), the socket path is different. Check with `ls /var/run/docker.sock` or `ls $XDG_RUNTIME_DIR/docker.sock`. **Missing /data volume:** Alert configurations are stored in `/data`. If you didn't mount `./dozzle_data:/data`, alert configs exist only in the container's ephemeral filesystem and are lost on restart. **Webhook URL misconfigured:** Test the webhook endpoint manually with `curl` from the Dozzle container to verify network reachability. **Rule syntax:** Double-check your alert rules in the Dozzle UI. Log patterns use substring matching, not regex (unless specified). **Ops notes:** - **Backup:** The `./dozzle_data` directory contains alert and notification configs. - **Updates:** `docker compose pull && docker compose up -d` - **Log retention:** Dozzle streams logs from Docker — it doesn't store them. Configure Docker log rotation to prevent disk filling. See [essential Docker commands](/docker-commands/) for log management. If disk is already full, [clean up Docker disk usage](/clean-docker-overlay2-dir/). ## Availability monitoring: Uptime Kuma Beszel watches resources from *inside* the server. Uptime Kuma checks HTTP, TCP, DNS, and ping reachability from *outside*. Different jobs, both needed. This is the standard small-fleet monitoring stack in 2026. [Uptime Kuma](https://github.com/louislam/uptime-kuma) is a self-hosted uptime monitoring tool with a clean UI, 90+ notification channels, built-in status pages, SSL certificate monitoring, and multi-language support. ~30–50 MB RAM, MIT license. For most self-hosters in 2026: **Beszel** (metrics) + **Dozzle** (logs) + **Uptime Kuma** (availability) covers everything you need. Total overhead: ~50–80 MB RAM. Quick deploy: ```yaml services: uptime-kuma: image: louislam/uptime-kuma:latest container_name: uptime-kuma restart: unless-stopped volumes: - ./uptime-kuma-data:/app/data ports: - 3001:3001 ``` **Verify:** Open `http://your-ip:3001`, create your admin account, and add an HTTP monitor for your own server. It should show "Up" within a few seconds. For detailed setup guides, see [how to install Uptime Kuma](/install-uptime-kuma/) or [deploy Uptime Kuma with one click](/deploy-uptime-kuma/). For the complete Beszel + Uptime Kuma integration, see [pairing Beszel with Uptime Kuma](/beszel-uptime-kuma/). ## Tool comparison table Updated August 2026. Version numbers and RAM figures based on current releases and independent benchmarks. | Feature | Beszel v0.18 | Netdata v2.10 | Prometheus 3.x / Grafana 12.x | Dozzle v10 | Uptime Kuma | |---|---|---|---|---|---| | **Primary purpose** | Lightweight metrics | Deep real-time metrics | Enterprise metrics | Log viewing + alerts | Availability | | **RAM usage** | ~10–25 MB | 200–500 MB | 500 MB–1 GB+ | ~10–18 MB | ~30–50 MB | | **Setup complexity** | Very low | Low | High | Very low | Low | | **Learning curve** | Gentle | Moderate | Steep | Gentle | Gentle | | **Docker stats** | Built-in | Built-in | Via cAdvisor | N/A (logs only) | N/A | | **GPU monitoring** | NVIDIA, AMD, Intel, Apple Silicon | Via go.d/nvidia_smi | Via custom exporters | N/A | N/A | | **S.M.A.R.T. disks** | Built-in with failure alerts | Via collectors | Via custom exporters | N/A | N/A | | **Alerts** | Built-in (ntfy, email, webhook) | Built-in, 90+ channels | Alertmanager | Webhooks | Built-in, 90+ channels | | **OAuth/Multi-user** | Built-in (OAuth2/OIDC) | Cloud plans only | Grafana built-in | File-based auth | Built-in | | **Open source** | MIT | GPL-3.0+ | Apache-2.0 / AGPLv3 | MIT | MIT | ## Security & production hardening Every monitoring tool in this article exposes a web interface and most need access to the Docker socket. Treat these like any other production service. **Reverse proxy + HTTPS:** Every tool should sit behind Caddy, Nginx, or Traefik with TLS. A minimal Caddy example for Beszel: ``` monitor.example.com { reverse_proxy http://localhost:8090 } ``` **Authentication:** Beszel has OAuth/OIDC built-in. Dozzle supports `DOZZLE_AUTH_PROVIDER=simple` for file-based auth or Authelia for forward proxy auth. Grafana has built-in auth with RBAC. Netdata Cloud handles auth server-side. **Docker socket security:** All these tools mount `/var/run/docker.sock`. This is root-equivalent access — anyone with the socket can control your containers. Always use read-only mounts (`:ro`) and consider a [Docker socket proxy](https://github.com/Tecnativa/docker-socket-proxy) for production to limit the API surface. If your only server dies, your monitoring dies with it. You'll have no metrics, no logs, and no idea what happened. Run the Beszel hub on a separate box — even a $3/month VPS works. The hub is ~12 MB RAM. Cheap options: [Hetzner VPS](https://go.bitdoze.com/hetzner) (CX22), [Vultr](https://go.bitdoze.com/vultr), or [DigitalOcean](https://go.bitdoze.com/do). For a home setup, a mini PC with [dedicated home server hardware](/best-mini-pc-home-server/) works too. Check your [Docker firewall configuration](/docker-bypasses-firewall/) — Docker can bypass UFW/iptables rules by default. And [secure your server](/secure-ssh-server-linux/) with proper SSH hardening before exposing any monitoring dashboards. ## Post-deploy checklist After deploying your monitoring stack, run through this list: - All agents reporting green in the dashboard - Alerts configured with meaningful thresholds (not defaults) - Alert tested — trigger one intentionally and confirm delivery to your notification channel - Data directories backed up (Beszel: `/beszel_data`, Dozzle: `/data`, Netdata: config volumes) - Reverse proxy + HTTPS configured for all web UIs - Anonymous analytics disabled if desired (`DOZZLE_NO_ANALYTICS=true`) - Firewall rules verified — only necessary ports exposed to the internet - Docker socket mounts are read-only (`:ro`) where possible ## Conclusions The monitoring landscape in 2026 is generous to self-hosters. You don't need to pay Datadog $15/host/month. Here's the decision tree: **For 90% of readers** (solo devs, 1–20 VPS boxes, Docker): deploy Beszel + Dozzle + Uptime Kuma. Total RAM: ~50–80 MB. Cost: free. Setup time: under an hour. This is the stack I'd recommend to anyone starting fresh. **If you need deep observability** (per-second metrics, AI anomaly detection, 800+ integrations): Netdata with the Homelab plan ($90/year for unlimited nodes). Budget 200–500 MB RAM. Worth it when you're debugging production issues that need sub-second resolution. **If you're running an organization** with 50+ targets, custom dashboards, and PromQL queries: Prometheus + Grafana. Budget 1 GB+ RAM and a weekend for initial setup. The learning curve is real, but the flexibility is unmatched. New to server monitoring? Deploy Beszel hub + agent on two servers. You'll have metrics in 5 minutes and it costs you nothing. Expand to Dozzle for logs and Uptime Kuma for availability as you grow.

Wezterm Mac Setup: The Ultimate Terminal with Tmux & Zoxide

Fri, 07 Aug 2026 00:00:00 GMT

import Notice from "@components/widgets/Notice.astro"; import Tabs from "@components/widgets/Tabs.astro"; import Tab from "@components/widgets/Tab.astro"; import Accordion from "@components/widgets/Accordion.astro"; [Wezterm](https://wezfurlong.org/wezterm/) is a modern terminal emulator written in Rust that I keep coming back to. It's GPU-accelerated, configurable via Lua scripts, and has a built-in multiplexer. All things that matter when you live in a terminal eight hours a day. Key features: 1. **GPU acceleration** for smooth scrolling, even with heavy output. 2. **Lua configuration**: programmable, not just a static config file. 3. **Built-in multiplexer**: panes, tabs, and workspaces without tmux. 4. **Ligature support** for programming fonts. 5. **Cross-platform**: macOS, Windows, Linux with the same config. 6. **True color (24-bit)** and a large built-in color scheme library. 7. **Image rendering** directly in the terminal. Ghostty 1.0 (released December 2024) is another solid macOS-native option if you want a Zig-based terminal with native look and feel. Wezterm still wins for me on Lua configurability, built-in multiplexing, and cross-platform config portability. If you want to explore Ghostty, check the [Ghostty terminal setup guide](/ghostty-terminal/). All tools in this guide (Wezterm, Starship, tmux, zoxide, Homebrew) are free and open source (MIT or similarly permissive licenses). No subscriptions, no paid tiers. > If you are interested to see some free cool Mac Apps you can check [toolhunt.net mac apps section](https://toolhunt.net/mac/). ## Install and configure Wezterm on Mac Everything below flows from Homebrew. Once that's installed, the rest is copy-paste commands. ### Install Homebrew Open your terminal and run: ```sh /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)" ``` Follow the on-screen prompts. You may need your system password. Verify with: ```sh brew --version ``` If you hit permission errors, run `xcode-select --install` first to get the Xcode command-line tools, then retry. ### Install Wezterm ```sh brew install --cask wezterm ``` Launch from Applications or Spotlight (Cmd+Space, type "Wezterm"). ### Install Git ```sh brew install git ``` Verify: ```sh git --version ``` ### Install Meslo Nerd Font Nerd Fonts add programming-related glyphs (icons) to your terminal. Meslo is clear, readable, and widely supported. ```sh brew install font-meslo-lg-nerd-font ``` Restart Wezterm after installing the font. Wezterm now bundles Nerd Font Symbols v3.3.0 as a fallback, but installing Meslo explicitly gives the best experience with Powerlevel10k, Starship, or any prompt that uses icon glyphs. ### Setup Wezterm config file #### Create the config file ```sh touch ~/.wezterm.lua ``` Open it in your editor of choice: ```sh vim ~/.wezterm.lua ``` #### Configure Wezterm Paste this Lua config into `~/.wezterm.lua`: ```lua -- Pull in the wezterm API local wezterm = require("wezterm") -- This will hold the configuration. local config = wezterm.config_builder() -- This is where you actually apply your config choices config.font = wezterm.font("MesloLGS Nerd Font Mono") config.font_size = 19 config.window_decorations = "RESIZE|MACOS_USE_BACKGROUND_COLOR_AS_TITLEBAR_COLOR" config.window_background_opacity = 0.8 config.macos_window_background_blur = 10 -- my coolnight colorscheme: config.colors = { foreground = "#CBE0F0", background = "#011423", cursor_bg = "#47FF9C", cursor_border = "#47FF9C", cursor_fg = "#011423", selection_bg = "#033259", selection_fg = "#CBE0F0", ansi = { "#214969", "#E52E2E", "#44FFB1", "#FFE073", "#0FC5ED", "#a277ff", "#24EAF7", "#24EAF7" }, brights = { "#214969", "#E52E2E", "#44FFB1", "#FFE073", "#A277FF", "#a277ff", "#24EAF7", "#24EAF7" }, } -- and finally, return the configuration to wezterm return config ``` What this does: 1. Sets the font to Meslo Nerd Font Mono (the one we just installed). 2. Font size 19. Adjust to your display and preference. 3. `window_decorations = "RESIZE|MACOS_USE_BACKGROUND_COLOR_AS_TITLEBAR_COLOR"` gives you a resizable window with a titlebar that matches your terminal background. Looks cleaner on macOS. 4. Background at 80% opacity with a blur effect behind it (macOS only). 5. Custom "coolnight" color scheme: dark blue background with bright, readable text colors. After saving, Wezterm detects changes and shows an error window if there are deprecated or invalid fields. If everything looks right, the config applies automatically. You can also force a reload with `Ctrl+Shift+R`. #### New macOS-specific Wezterm tweaks These options only work on macOS: These config options have no effect on Linux or Windows. ```lua -- Extend terminal content behind the MacBook notch in fullscreen config.macos_fullscreen_extend_behind_notch = true -- Remove rounded corners (sharp square look) -- Add MACOS_FORCE_SQUARE_CORNERS to window_decorations: -- config.window_decorations = "RESIZE|MACOS_USE_BACKGROUND_COLOR_AS_TITLEBAR_COLOR|MACOS_FORCE_SQUARE_CORNERS" -- Center content when the window isn't an exact cell-multiple size config.window_content_alignment = "Center" ``` The notch support is nice on newer MacBooks. You get a few extra rows of terminal content in fullscreen mode. The titlebar color matching makes Wezterm blend with its own background instead of having a contrasting macOS titlebar strip. ### ⚠️ Powerlevel10k status and prompt options The maintainer has declared the project has "very limited support, no new features, most bugs will go unfixed." It still works today, but consider Starship below for an actively maintained alternative. Powerlevel10k (p10k) is still the most popular Zsh prompt (54k+ GitHub stars) and it still works. But the project is effectively frozen. If you're setting up fresh, Starship is the better bet. **Why Starship:** Cross-shell (zsh, fish, bash), written in Rust, actively maintained, simple TOML config. No zsh-specific lock-in. If you switch shells later (see the [Fish vs Zsh comparison](/fish-shell-vs-zsh/)), your prompt carries over. Install and activate: ```sh brew install starship echo 'eval "$(starship init zsh)"' >> ~/.zshrc source ~/.zshrc ``` Create a basic config at `~/.config/starship.toml`: ```toml # See https://starship.rs/presets/ for ready-made presets # Example: enable all default modules format = "$all" [git_status] format = '([$all_status$ahead_behind]($style) )' [nodejs] format = "via [🤖 $version](bold green) " ``` Starship ships with preset themes you can browse with `starship preset`. The Catppuccin Powerline preset is popular if you want a powerline-style look without manual config. For more on Starship, see the [Starship and Ghostty setup guide](/starship-ghostty-terminal/) or [Starship with Fish shell](/fish-shell-starship-prompt/) if you use Fish. p10k still works fine today. Install it if you want, but know that bugs won't be fixed. ```sh brew install powerlevel10k echo "source $(brew --prefix)/share/powerlevel10k/powerlevel10k.zsh-theme" >> ~/.zshrc source ~/.zshrc ``` On first load, the p10k configuration wizard walks you through prompt style, segments (git status, time, etc.), colors, and icon choices. You can re-run it anytime with `p10k configure`. Fine-tune later by editing `~/.p10k.zsh`. ### Setup zsh-autosuggestions plugin zsh-autosuggestions shows faded suggestions as you type, based on your command history. Press the right arrow key to accept a suggestion. ```sh brew install zsh-autosuggestions echo "source $(brew --prefix)/share/zsh-autosuggestions/zsh-autosuggestions.zsh" >> ~/.zshrc source ~/.zshrc ``` For more details on zsh autocomplete behavior, see the [comprehensive zsh autocomplete guide](/enable-command-autocomplete-in-zsh/). ### Setup zsh-syntax-highlighting zsh-syntax-highlighting colors commands as you type: valid commands in green, errors in red, existing file paths underlined. Catches typos before you hit enter. ```sh brew install zsh-syntax-highlighting echo "source $(brew --prefix)/share/zsh-syntax-highlighting/zsh-syntax-highlighting.zsh" >> ~/.zshrc source ~/.zshrc ``` For more customization options, check the [full zsh syntax highlighting guide](/enable-syntax-highlighting-zsh/). You can also browse more useful plugins in the [best Zsh plugins for 2026](/best-oh-my-zsh-plugins/). ## Enhance Wezterm with tmux and zoxide Wezterm is already capable on its own, but tmux and zoxide fill gaps that matter for real workflows: persistent sessions and fast directory jumping. ### What is tmux and how can it help tmux is a terminal multiplexer. It lets you create multiple terminal sessions inside a single window, detach from them, and reattach later. This is critical for remote server work: you can SSH in, start a tmux session, disconnect, and pick up right where you left off. tmux 3.6+ added scrollbars and Mode 2031 theming. `brew install tmux` gets you the latest version. Install and start: ```sh brew install tmux tmux ``` For a hands-on introduction, see the [tmux basics guide](/tmux-basics/). #### Wezterm built-in multiplexing vs standalone tmux Wezterm already has its own multiplexer: panes, tabs, and workspaces built right in. For purely local workflows (splitting your terminal into panes, switching between tabs), Wezterm's built-in mux is enough. You don't need tmux at all. Where tmux still wins: - **Persistent remote sessions**: SSH into a server, start tmux, detach, come back later. Wezterm's mux doesn't persist across SSH disconnects. - **Session sharing**: Two users can attach to the same tmux session (pair programming on a remote box). - **Reboot survival**: tmux sessions survive local reboots if the remote server stays up. If you only work locally, skip tmux and use Wezterm's built-in panes (`Ctrl+Shift+D` for horizontal split, `Ctrl+Shift+E` for vertical split). #### Wezterm tmux -CC control mode Wezterm now has "very usable" `tmux -CC` support. Running `tmux -CC` inside Wezterm starts tmux in control mode, where Wezterm acts as the GUI client. You get tmux's session persistence with Wezterm's rendering and keybindings. This is a hybrid option for power users who want the best of both. ### What is zoxide and how can it help zoxide replaces `cd` with a smarter version that learns from your usage. After a few days, `z project` jumps to `~/code/my-project` without typing the full path. It's one of those tools that feels like a small thing until you try going back. Install and activate: ```sh brew install zoxide echo 'eval "$(zoxide init zsh)"' >> ~/.zshrc source ~/.zshrc ``` Usage: replace `cd` with `z`. That's it. The more you use it, the smarter it gets. zoxide has a `doctor` subcommand that checks if your shell hooks are set up correctly. Run it if `z` doesn't seem to be working: ```sh zoxide doctor ``` For a deeper dive, see the [full zoxide guide](/zoxide/). ## Verify and troubleshoot your setup After completing all the steps above, run these checks to confirm everything works. ### Font verification Run this inside Wezterm: ```sh wezterm ls-fonts --text "Test" ``` It should list MesloLGS Nerd Font Mono. If it shows a fallback font, restart Wezterm or check that the font name in your config matches exactly. ### Config error detection Wezterm now shows an error window if your `~/.wezterm.lua` has deprecated or invalid fields. If you see this window after editing your config: 1. Read the error message. It names the specific field. 2. Fix the Lua syntax or field name. 3. Press `Ctrl+Shift+R` to reload the config without restarting Wezterm. `Ctrl+Shift+L` opens the debug overlay / Lua REPL, useful for inspecting errors or testing config values live. ### zoxide and prompt diagnostics ```sh # Check zoxide shell integration zoxide doctor # Verify terminal type echo $TERM # Should show: xterm-256color # Starship: browse available presets starship preset # Powerlevel10k: re-run configuration wizard p10k configure ``` ### Common failure modes Run `xcode-select --install` first to get the Xcode command-line tools, then retry the `brew install` command. Restart Wezterm after installing the font. Run `wezterm ls-fonts --text "Test"` to confirm which font is active. Make sure the font name in your `.wezterm.lua` matches what Homebrew installed. The name is case-sensitive. Make sure `eval "$(zoxide init zsh)"` is in your `~/.zshrc`. Open a new terminal tab or run `source ~/.zshrc`. Run `zoxide doctor` to diagnose further. For Starship: run `starship preset` to browse presets, or check that `eval "$(starship init zsh)"` is the last prompt-related line in your `~/.zshrc`. For Powerlevel10k: run `p10k configure` to re-run the wizard. If colors look wrong in tmux, add `set -g default-terminal "tmux-256color"` to `~/.tmux.conf`. ## Alternative: Ghostty terminal Ghostty 1.0 (released December 2024) is a macOS-native terminal written in Zig by Mitchell Hashimoto. It's fast, GPU-accelerated, and feels native on macOS in a way that few cross-platform terminals do. Where Wezterm still has the edge: - **Lua configuration**: Wezterm's config is a full programming language. Conditional logic, functions, dynamic values. Ghostty uses a simpler key-value format. - **Built-in multiplexer**: Wezterm's panes and workspaces work without tmux. Ghostty has no built-in mux. - **Cross-platform**: Same `.wezterm.lua` works on macOS, Linux, and Windows. Ghostty is still catching up on Linux. If you're curious about Ghostty, see the [Ghostty terminal setup guide](/ghostty-terminal/). For a prompt setup that works great with either terminal, check the [Starship and Ghostty setup guide](/starship-ghostty-terminal/). ## Conclusion You now have a terminal stack built from free, open-source tools: Wezterm as the emulator, Starship (or p10k) for the prompt, tmux for persistent sessions, and zoxide for fast directory jumping. Everything here runs on macOS with Homebrew. No paid apps, no subscriptions. Wezterm's Lua config makes it uniquely flexible among modern terminals. You can tweak colors, keybindings, window behavior, and conditional logic all in one file. Start with the config above, then experiment. If you want to go deeper, explore the [Starship and Ghostty setup guide](/starship-ghostty-terminal/) or browse the [top Fish shell plugins](/best-fish-shell-plugins/) if you're considering switching shells.

How to Identify Processes Using Swap Space in Linux

Fri, 07 Aug 2026 00:00:00 GMT

import Notice from "@components/widgets/Notice.astro"; import ListCheck from "@components/widgets/ListCheck.astro"; import Tabs from "@components/widgets/Tabs.astro"; import Tab from "@components/widgets/Tab.astro"; When a Linux server starts swapping, performance tanks. The problem: standard tools like `docker stats` and even `top` don't always show you the real swap picture. You need to know which processes are actually consuming swap space so you can fix the root cause, not just throw RAM at it. This guide covers three reliable approaches: `smem` (the tool I reach for first), reading `/proc` directly (no dependencies needed), and `vmstat` for detecting active swap thrashing. You'll also get practical coverage of swappiness tuning, container swap tracking with cgroups v2, and modern compressed swap with zswap/zram. All of it applies to any Linux distro: Ubuntu, Debian, RHEL, Fedora, and the rest. If you need a broader refresher on Linux administration, start with these [essential Linux commands](https://www.bitdoze.com/linux-commands/). ## Quick diagnostic: 30-second swap health check Before diving into per-process details, run these three commands to gauge whether you even have a problem. If swap is under 20% and vmstat shows si/so near zero, you're fine. The rest of this guide is optional reading.

free -h: Shows total/used/available swap at a glance
smem -s swap -r -k | head: Top swap-consuming processes (install smem first if needed)
vmstat 1 5: Shows if swap is actively being read/written (si/so columns)

```bash # 1. System-wide memory overview free -h # 2. Top 10 swap consumers smem -s swap -r -k | head -10 # 3. Is swap actively being used? (5 samples, 1s interval) vmstat 1 5 ``` **What "healthy" looks like:** - `free -h`: Swap used under 20% of total, "available" column still has headroom - `smem`: Most processes show 0 kB swap, top consumer under 50 MB - `vmstat`: `si` and `so` columns at 0 or near-zero **What "concerning" looks like:** - `free -h`: Swap used climbing past 50%, "available" under 1 GB - `vmstat`: `si`/`so` consistently in the hundreds of KB/s, the system is actively thrashing For more on [monitoring system resources on Linux](https://www.bitdoze.com/monitor-cpu-usage-and-send-email-alerts-in-linux/), including alerting when swap usage spikes. ## Understanding Linux swap space Swap space acts as overflow for physical RAM. When the kernel runs low on memory, it moves less-frequently-used pages to swap, a partition or file on disk. This prevents the OOM killer from firing immediately, but at a cost: disk I/O is orders of magnitude slower than RAM. Without any swap, hitting the memory ceiling means the OOM killer starts terminating processes. With swap, the system degrades gradually instead of crashing, but excessive swapping ("thrashing") can make the system feel frozen. ### Swap partition vs swap file | | Swap Partition | Swap File | |---|---|---| | Setup | Dedicated partition on disk | Regular file in a filesystem | | Performance | Slightly better on spinning disks (avoids filesystem overhead) | On SSDs, the difference is negligible | | Flexibility | Fixed size, requires repartitioning to resize | Easy to create, resize, or remove | | Caveats | N/A | btrfs has restrictions on swap files (must be on a non-compressed, non-COW subvolume) | On a typical VPS or home server with SSDs, swap files are the pragmatic default. No partitioning needed, and you can [set up shared storage on Linux](https://www.bitdoze.com/setup-nfs-linux/) alongside swap without worrying about partition layout. ### How much swap should you allocate? | System RAM | Recommended Swap | Notes | |---|---|---| | 2 GB or less | 2x RAM | Desktops, small VPS | | 2-8 GB | Equal to RAM | General-purpose servers | | 8-64 GB | 0.5x RAM | High-memory servers | | 64 GB+ | Minimum 4 GB | Large production servers | These are rough guidelines. Modern RHEL documentation says swap sizing depends on workload and whether you use hibernation, not just RAM size. Most cloud providers ship VPS instances with zero swap. For a server running Docker containers or databases, a 1-2 GB swap file is a cheap safety net. If you're [setting up a home server](https://www.bitdoze.com/best-mini-pc-home-server/), the same logic applies. A small swap file prevents OOM kills during memory spikes. ## Check per-process swap usage with smem `smem` is the best tool for this job. It reads swap data from `/proc` but gives you sorting, filtering, per-user views, and human-readable output. It's packaged in every major distro. ### Installing smem ```bash sudo apt install smem ``` ```bash sudo dnf install smem ``` Verify the installation: ```bash smem --version ``` **Failure mode:** If you get "command not found" after installing, your distro may not package it. Fallback: `pip install smem` (requires Python 3). ### Top swap-consuming processes ```bash smem -s swap -r -k ``` Flags: `-s swap` sort by swap column, `-r` reverse (descending), `-k` show units in KB/MB/GB. Sample output: ``` PID User Command Swap USS PSS RSS 1315 root /usr/bin/python litellm 60.1M 89.2M 91.4M 98.1M 1746 root /usr/bin/python gunicorn 109.4M 112.3M 114.8M 120.2M 1588 root node next-server (v14) 41.5M 52.1M 54.3M 60.8M 780 root /usr/bin/containerd 3.3M 18.7M 19.2M 25.4M 875 root /usr/bin/dockerd 6.4M 42.1M 43.8M 52.3M ``` The **Swap** column is what matters here. USS (Unique Set Size) and PSS (Proportional Set Size) show physical memory usage, useful context but separate from swap. ### Filtering by process name ```bash # Only postgres processes smem -P postgres -s swap -r # Per-user view (useful for multi-tenant servers) smem -u -s swap -r # Show percentages instead of absolute values smem -s swap -r -p | head -20 ``` These are practical for Docker/Dokploy hosts where you want to quickly check if a specific database or application is the swap hog. ## Using /proc to find swap usage by process When you can't install `smem` (minimal containers, restricted environments), the `/proc` filesystem has everything you need. This is what `smem` reads under the hood. ### Reading VmSwap from /proc/PID/status The kernel tracks per-process swap in `/proc//status` as the `VmSwap` field: ```bash # Check swap for a specific PID grep VmSwap /proc/1438/status ``` ``` VmSwap: 512 kB ``` One-liner to list all processes with non-zero swap: ```bash for f in /proc/[0-9]*/status; do awk '/^Name:/{n=$2} /^Pid:/{p=$2} /^VmSwap:/{if($2>0) print p, $2, n}' "$f" 2>/dev/null done | sort -k2 -nr | head -20 | column -t ``` **Failure mode:** "No such file or directory" errors are normal. A process can exit between the moment you start iterating and the moment you read its `/proc` entry. Ignore them. ### The smaps_rollup method (kernel 4.14+) For an efficient aggregate of all memory mappings, `smaps_rollup` is faster than reading the full `smaps` file (which can be thousands of lines per process): ```bash # All processes with non-zero swap, sorted descending grep -H 'Swap:' /proc/*/smaps_rollup 2>/dev/null | awk -F'[: ]' '{print $1, $4}' | sort -t: -k2 -nr | head -20 ``` `/proc/*/smaps_rollup` has been available since kernel 4.14 (2017). Every currently supported distro has it. ```bash # Verify your kernel version uname -r ``` Note: Reading the full `/proc//smaps` for every process is expensive. `htop` had performance issues with this (see [htop issue #1712](https://github.com/htop-dev/htop/issues/1712)). Use `smaps_rollup` instead. ### Clean awk script (no dependencies) Save this as `swap-users.sh` for a reusable, readable script: ```bash #!/bin/bash # swap-users.sh - List processes using swap, sorted by usage printf '%-10s %12s %s\n' "PID" "Swap" "Command" for s in /proc/[0-9]*/status; do awk '/^Name:/{n=$2} /^Pid:/{p=$2} /^VmSwap:/{if($2>0) printf "%-10s %10s kB %s\n",p,$2,n}' "$s" 2>/dev/null done | sort -k2 -n -r ``` Make it executable and run: ```bash chmod +x swap-users.sh ./swap-users.sh ``` Output: ``` PID Swap Command 1746 112000 kB gunicorn 1387 12416 kB gunicorn 449142 17536 kB node 1588 42496 kB next-server 1315 61568 kB litellm 812 9344 kB unattended-upgr 875 6528 kB dockerd 780 3328 kB containerd ``` **Verify:** Output should be sorted by swap usage descending. Empty output means no processes are using swap (which is fine). For a quick inline version without saving a file: ```bash for f in /proc/[0-9]*/status; do awk '/^Name:/{n=$2}/^Pid:/{p=$2}/^VmSwap:/{if($2>0)print p,$2,n}' "$f" 2>/dev/null done | sort -k2 -nr | head -20 | column -t ``` ## Other tools: top, htop, and vmstat The original article mentioned `top` and `htop` as monitoring tools. There are important caveats. ### top's SWAP column: what it actually shows If your top shows processes using hundreds of MB of swap while free -h shows only a few MB total, you're running the old procps top that computes SWAP = VIRT - RES. This is not real swap usage. It includes memory-mapped files, video memory, and other virtual memory. Upgrade to procps-ng (standard on Ubuntu 16.04+, RHEL 7+, Debian 9+) or use smem instead. On modern distros, `top` from procps-ng (version 3.3.10+) reads `VmSwap` from `/proc` correctly. Check your version: ```bash top -v ``` If it shows `procps-ng` and a version ≥3.3.10, the SWAP column is accurate. If it shows just `procps` (no `-ng`), treat the SWAP column as fiction. Source: [Red Hat KB 237633](https://access.redhat.com/solutions/237633), [htop FAQ](https://hisham.hm/htop/index.php?page=faq) ### Why htop doesn't have a SWAP column htop deliberately omits a per-process swap column. The reason: shared memory pages make per-process swap accounting unreliable. A shared library page can be "charged" to multiple processes, inflating the numbers. The htop developers decided it was better to show no swap column than a misleading one. Use `smem` or the `/proc` methods above for per-process swap data. ### Detecting swap thrashing with vmstat `vmstat` shows real-time swap activity. The `si` (swap in) and `so` (swap out) columns are the key indicators: ```bash vmstat 1 5 ``` ``` procs -----------memory---------- ---swap-- -----io---- -system-- ------cpu----- r b swpd free buff cache si so bi bo in cs us sy id wa st 1 0 294000 678528 12032 5712832 0 0 2 15 89 12 3 1 96 0 0 0 0 294000 678528 12032 5712832 0 0 0 0 102 15 2 1 97 0 0 0 0 294000 678528 12032 5712832 0 0 0 0 98 12 1 1 98 0 0 ```

si/so near zero: Normal. Swap space is allocated but not actively being read/written.
si/so in the hundreds of KB/s: Actively swapping. Investigate with smem.
si/so in the thousands of KB/s: Thrashing. The system is spending more time swapping than doing work. Take action immediately.

With `sysstat` installed, you can also use: ```bash # Swap activity report (10 samples, 1s interval) sar -S 1 10 # Page fault and paging rate sar -B 1 10 ``` If swap thrashing is impacting your server performance, consider [benchmarking your cloud server](https://www.bitdoze.com/benchmark-cloud-servers/) to compare upgrade options. ## Swap and Docker containers If you run Docker or Dokploy, this section is critical. Standard container monitoring doesn't show swap at all. ### Why docker stats doesn't show swap `docker stats` shows a "MEM USAGE" column, but that's RSS + page cache. It does not include swap. A container could be swapping heavily and `docker stats` would show nothing unusual. This is a common blind spot for anyone [monitoring server and Docker resources](https://www.bitdoze.com/sever-monitoring/). The memory numbers in `docker stats` look fine while the system is actually thrashing because a container's anonymous pages are piling up in swap. For [Docker management commands](https://www.bitdoze.com/docker-commands/) beyond memory monitoring. ### Tracking container swap with cgroups v2 On systems with cgroups v2 (default on Ubuntu 22.04+, Fedora 31+, Debian 11+), you can read per-container swap usage directly: ```bash # Check cgroups version (should show "cgroup2fs") stat -fc %T /sys/fs/cgroup/ # Swap used by a specific container cat /sys/fs/cgroup/system.slice/docker-.scope/memory.swap.current ``` The value is in bytes. Convert to MB: divide by 1048576. Loop through all containers: ```bash for cg in /sys/fs/cgroup/system.slice/docker-*.scope; do name=$(basename "$cg") bytes=$(cat "$cg/memory.swap.current" 2>/dev/null) if [ -n "$bytes" ] && [ "$bytes" -gt 0 ]; then mb=$((bytes / 1048576)) echo "$name: ${mb} MB" fi done ``` This only works on cgroups v2. If stat -fc %T /sys/fs/cgroup/ returns tmpfs instead of cgroup2fs, you're on cgroups v1. Enabling cgroups v2 requires kernel boot parameters. Check your distro documentation. Also useful: if you're [reclaiming disk space from Docker](https://www.bitdoze.com/clean-docker-overlay2-dir/), remember that swap files also consume disk space. ## Tuning swap behavior with vm.swappiness The existing swappiness guidance in most articles is oversimplified or outdated. Here's what actually matters. ### What swappiness actually controls Swappiness is not "how aggressively the kernel swaps." It controls the kernel's weighting between reclaiming two types of memory pages: - **File-backed pages** (page cache) — reading them back from disk is fast (sequential I/O on the filesystem) - **Anonymous pages** (application memory) — reading them back requires swap I/O (random I/O) A higher swappiness value tells the kernel to prefer evicting anonymous pages to swap. A lower value tells it to prefer dropping page cache. On SSDs, the cost of reading swap is similar to reading page cache, so higher swappiness values (100) are reasonable. On spinning disks, swap reads are expensive random I/O, so lower values make more sense. Source: Chris Down, [In defence of swap](https://chrisdown.name/2018/01/02/in-defence-of-swap.html) ### Swappiness 0-200: kernel 5.8+ changes Since kernel 5.8 (August 2020), `vm.swappiness` accepts values 0-200, not just 0-100. Values above 100 bias more heavily toward swapping anonymous pages. Critical distinction: | Value | Behavior | |---|---| | **0** | Never swap anonymous pages unless the system is near OOM (special semantics since kernel 3.5, 2012) | | **1** | Lowest "normal" value — avoids swap but doesn't have the special-case behavior of 0 | | **60** | Default on most distros. Balanced for general use | | **100** | Treats file and anonymous pages equally. Good default for SSD-based systems | ### Persistent configuration with sysctl.d The old approach of appending to `/etc/sysctl.conf` works but is messy. The modern method uses drop-in files: ```bash # Check current value sysctl vm.swappiness # Apply temporarily (resets on reboot) sudo sysctl -w vm.swappiness=60 # Apply permanently with a drop-in file echo 'vm.swappiness=60' | sudo tee /etc/sysctl.d/99-swap.conf sudo sysctl --system ``` Verify the change took effect: ```bash sysctl vm.swappiness ``` **Failure mode:** Value not persisting after reboot? Another file in `/etc/sysctl.d/` might be overriding it. Check with: ```bash sudo sysctl --system 2>&1 | grep swappiness ``` ## Modern swap technologies: zswap and zram If you're running Linux 5.x+, there are better options than raw disk swap alone. ### zswap: compressed write-back cache zswap sits between the kernel's memory allocator and disk swap. When the kernel wants to swap a page out, zswap compresses it first. If the compressed page fits in a RAM cache, no disk I/O happens. When the cache fills up, the least-recently-used pages get written to disk swap automatically. This is the "enable and forget" option for most servers. On a VPS with SSD-backed swap, zswap reduces disk swap writes significantly. Add zswap.enabled=1 to your kernel command line (via GRUB or bootloader config). It's a free performance win — compressed pages stay in RAM when possible, and only hit disk when necessary. Check if zswap is active: ```bash dmesg | grep zswap cat /sys/module/zswap/parameters/enabled ``` ### zram: compressed RAM block device zram creates a compressed block device entirely in RAM and uses it as swap. No disk I/O at all. Everything stays in memory, just compressed. Fedora uses zram by default (paired with `systemd-oomd`). The tradeoff: zram has a hard capacity limit (typically 50% of RAM) and can cause LRU inversion when used alongside disk swap. It's best for memory-constrained systems like laptops and containers, not general-purpose servers. For most VPS/Dokploy setups, zswap with disk swap is the better choice. ## Swap troubleshooting and verification ### How to verify swap is active ```bash # List all active swap devices with priorities cat /proc/swaps # Human-readable version swapon --show # Quick check free -h ``` If `swapon --show` returns nothing, you have no swap configured. For most cloud VPS instances, this is the default — you need to [create a swap file](#how-much-swap-should-you-allocate) manually. ### When swap is normal vs. when it's a problem Swap used 10–20%, vmstat si/so near zero. The kernel is keeping cold pages in swap to free up RAM for active workloads. This is expected behavior and not a problem. Swap growing steadily over time, vmstat si/so consistently in the hundreds of KB/s or higher. The system is thrashing — spending more time swapping pages than doing actual work. Add RAM, kill processes, or optimize memory-hungry applications. The distinction: swap *allocation* (pages sitting in swap) is fine. Swap *activity* (pages being constantly moved between RAM and swap) is the problem. `vmstat` si/so columns tell you which one you have. ### How to safely clear swap To move all swap pages back to RAM: ```bash sudo swapoff -a && sudo swapon -a ``` Before clearing swap, run free -h and confirm that available RAM is greater than swap used. If there's not enough free RAM, swapoff will hang or trigger the OOM killer. Stop memory-heavy services first if needed. Verify swap cleared: ```bash free -h # Swap used should drop to near zero ``` ### Using systemd-oomd to prevent swap storms On Ubuntu 22.04+ and Fedora, `systemd-oomd` is enabled by default. It uses PSI (Pressure Stall Information) to detect when the system is under memory pressure and kills memory-hungry processes before swap fills up completely. Check if it's running: ```bash systemctl status systemd-oomd ``` If it's not active and you're on Ubuntu 22.04+ or Fedora, enable it: ```bash sudo systemctl enable --now systemd-oomd ``` For older distros, `earlyoom` is a simpler alternative available in most repos: ```bash sudo apt install earlyoom # Debian/Ubuntu sudo dnf install earlyoom # RHEL/Fedora sudo systemctl enable --now earlyoom ``` ## Conclusion Three things to remember about swap on Linux: 1. **Use `smem` as your go-to tool.** `smem -s swap -r -k` gives you the clearest, most accurate per-process swap picture. Fall back to `/proc` scripts when you can't install packages. 2. **vmstat si/so is the real danger signal.** Swap allocation is normal. Swap activity (high si/so) means the system is thrashing and needs attention. 3. **Enable zswap on SSD-based servers.** It's a one-line kernel parameter that reduces disk swap writes for free. If you're consistently hitting swap limits, the fix is usually more RAM — not more tuning. For affordable VPS upgrades, [Hetzner Cloud VPS](https://go.bitdoze.com/hetzner) starts at a few euros per month with SSD storage. [Hostinger VPS](https://go.bitdoze.com/hostinger-vps) and [Vultr](https://go.bitdoze.com/vultr) are solid alternatives with global datacenter coverage. [DigitalOcean](https://go.bitdoze.com/do) is another option if you want a developer-friendly platform. For more Linux administration guides, check out our [essential Linux commands](https://www.bitdoze.com/linux-commands/) reference and the guide to [monitoring system resources on Linux](https://www.bitdoze.com/monitor-cpu-usage-and-send-email-alerts-in-linux/) with email alerts.

Configure Postfix to Send Email Using External SMTP Servers

Thu, 06 Aug 2026 00:00:00 GMT

import YouTubeEmbed from "../../components/widgets/YouTubeEmbed.astro"; import Notice from "../../components/widgets/Notice.astro"; import ListCheck from "../../components/widgets/ListCheck.astro"; import Tabs from "../../components/widgets/Tabs.astro"; import Tab from "../../components/widgets/Tab.astro"; import Button from "../../components/widgets/Button.astro"; Postfix is a mail transfer agent (MTA) that handles sending, routing, and delivering email on Unix-like systems. Most VPS setups only need a send-only SMTP server. Something that takes outgoing mail from your applications and hands it off to a real provider. That's exactly what configuring Postfix to send email using external SMTP servers gives you: a lightweight local relay that forwards everything through Brevo, Mailgun, Amazon SES, or another provider you trust. This postfix send-only SMTP server setup is useful for everything from cron job notifications to [sending email alerts from your Linux server](/monitor-cpu-usage-and-send-email-alerts-in-linux). Below you'll get the full configuration, an automated script, and the troubleshooting I wish I'd had the first time around. ## Why use Postfix with an external SMTP service Running your own mail server that delivers directly to recipients is a headache you don't want. IP reputation management, blacklist monitoring, DKIM key rotation. It's a full-time job. External SMTP providers handle all of that. Here's why the relay pattern works: - **Better deliverability.** Providers like Brevo and Mailgun maintain relationships with Gmail, Outlook, and Yahoo. Your emails actually reach inboxes instead of spam folders. - **Reduced server load.** Postfix hands off the message to the provider's servers. Your VPS doesn't maintain outbound SMTP connections to dozens of recipient domains. - **Simplified maintenance.** No SPF/DKIM key management on your server, no IP blacklist monitoring, no reverse DNS configuration. The provider handles it. - **Cost-effective.** Free tiers from Brevo (300/day) or SMTP2GO (1,000/month) cover most personal and small-business workloads. - **Scalability.** Need to send 50,000 emails? Your VPS config doesn't change. You just upgrade your provider plan. - **Compliance.** External providers help with GDPR, CAN-SPAM, and CASL requirements through built-in unsubscribe handling and consent tracking. ## SMTP relay services you can use with Postfix Not all SMTP providers are equal on pricing, deliverability, and ease of setup. Here's a comparison of the ones worth considering, then details on each. | Provider | Free Tier | Paid Starting Price | Notes | |----------|-----------|-------------------|-------| | **Brevo** | 300/day (~9,000/month) | $9/month (Starter) | Best free option, permanent free tier | | **Mailgun** | 100/day (~3,000/month) | $15/month (Basic) | Permanent free tier, strong API | | **Amazon SES** | 3,000 messages/month (12 months) | $0.10/1,000 emails | Cheapest at scale, best for AWS users | | **mail.baby** | None | $1/month + $0.20/1,000 | Cheapest paid option, unlimited domains | | **SMTP2GO** | 1,000/month | $15/month (Starter) | No credit card needed, good SendGrid replacement | | **Resend** | 3,000/month (100/day) | $20/month (Pro) | Modern, API-first, developer-focused | | **Zeptomail** | 10,000 emails (1-month trial) | Credit-based | Zoho ecosystem, pay-as-you-go after trial | | **SendGrid** | 60-day trial only | $19.95/month (Essentials) | No longer has a permanent free tier | Verify current tiers on each provider's website before committing. Prices listed here are accurate as of July 2025. ### Brevo free SMTP relay [Brevo](https://www.brevo.com/) (formerly Sendinblue) remains the best free SMTP relay for Postfix. The permanent free tier gives you 300 emails per day (about 9,000 per month) with no credit card required. - SMTP server: `smtp-relay.brevo.com:587` - Good deliverability rates across major providers - Email tracking and templating on the free plan - API access if you need more than SMTP For most personal projects and small VPS workloads, Brevo's free tier is enough. I default to it unless there's a reason not to. ### Mailgun SMTP relay [Mailgun](https://www.mailgun.com/) updated its free tier. It's now **100 emails per day** on a permanent free plan (no expiration). Previously it was 5,000 emails for 3 months, which sounded better but had a time limit. - Powerful API for developers who need more than basic SMTP - Good documentation and support - Email validation and domain authentication included - Flexible pricing if you outgrow the free tier ### Amazon SES SMTP relay Amazon SES pricing changed significantly. The old "62,000 free emails from EC2" tier was replaced in August 2023. The current model: - **3,000 message charges per month free for the first 12 months** after you start using SES - After that: $0.10 per 1,000 emails (plus data transfer) - New AWS customers (as of July 2025) can get up to $200 in Free Tier credits across AWS services, valid for 12 months SES is the cheapest option at scale but requires more setup (IAM policies, sandbox mode exit). Best if you're already running on AWS and need high volume. ### mail.baby SMTP relay [mail.baby](https://www.mail.baby/) is the budget option: $1/month plus $0.20 per 1,000 emails. No free tier, but the pricing is hard to beat for low-volume paid email. Unlimited domains on all plans, simple setup, 24/7 support. For more details, see the [detailed mail.baby review](/mail-baby-review). ### SMTP2GO [SMTP2GO](https://www.smtp2go.com/) is a solid alternative now that SendGrid killed its free tier. The free forever plan includes 1,000 emails per month with no credit card required. Setup is straightforward, deliverability is good, and the dashboard is clean. ### Resend [Resend](https://resend.com/) is a newer, API-first SMTP provider aimed at developers. Free tier: 3,000 emails/month (100/day). The modern developer experience and React Email integration make it appealing if you're building apps, though it works fine as a plain SMTP relay too. ### Zeptomail SMTP relay [Zeptomail](https://www.zoho.com/zeptomail/) from Zoho no longer has a perpetual free tier. You get **one free credit (10,000 emails) valid for 1 month** as a trial. After that, it's credit-based pricing (1 credit = 10,000 emails, credits valid for 6 months). Pricing is not publicly listed in USD. You contact sales. Good if you're in the Zoho ecosystem. For a [step-by-step ZeptoMail SMTP relay guide](/how-to-setup-smtp-relay-email-on-zeptomail), see the dedicated article. ### SendGrid SMTP (trial only) New accounts get a 60-day free trial (100 emails/day), then paid plans start at $19.95/month (Essentials). There is no longer a permanent free tier. Consider SMTP2GO, Brevo, or Mailgun as free alternatives. [SendGrid](https://sendgrid.com/) is owned by Twilio. It's still a capable platform with high deliverability and solid APIs. But at $19.95/month minimum, it's no longer the go-to for hobby projects. I'd pick Brevo or SMTP2GO for free-tier needs. ## Prerequisites Before configuring Postfix, make sure you have:

A Linux VPS with Debian/Ubuntu (this guide uses apt commands)
A domain with DNS records (SPF, DKIM, DMARC) configured with your SMTP provider
An SMTP provider account with credentials ready
Root or sudo access
Outbound port 587 (STARTTLS) unblocked by your VPS provider

### Install required packages ```sh sudo apt update && sudo apt install -y postfix libsasl2-modules mailutils ``` Without `libsasl2-modules`, Postfix cannot authenticate with your SMTP provider. You'll get "SASL authentication failure: No worthy mechs found" in the mail log. This package is not installed by default on minimal Debian/Ubuntu images. Always include it. Also make sure CA certificates are installed (for TLS verification): ```sh sudo apt install -y ca-certificates ``` **Verify:** Run `postconf -m | grep sasl`. You should see SASL mechanisms listed (LOGIN, PLAIN, etc.). If the command returns nothing, `libsasl2-modules` is missing. ### DNS records (SPF, DKIM, DMARC) Your emails will land in spam regardless of your Postfix configuration if DNS records are missing. Your SMTP provider gives you the specific values to add. At minimum, you need: - **SPF TXT record**: authorizes your provider to send on behalf of your domain (e.g., `v=spf1 include:brevo.com ~all`) - **DKIM public key**: added as a TXT record so recipient servers can verify message signatures - **DMARC policy**: tells receiving servers what to do with messages that fail SPF/DKIM checks Each provider has its own documentation for these. Set them up before testing. Otherwise your test emails will go straight to spam. ### VPS port requirements Many budget VPS providers block outbound ports 25, 587, and 465 by default to prevent spam. This includes [Hetzner](https://go.bitdoze.com/hetzner), OVH, Contabo, and Netcup. You'll need to open a support ticket asking them to unblock port 587 (STARTTLS) for your server. To [check if your SMTP ports are reachable](/check-remote-port-in-linux-nc), use `nc`: ```sh nc -zv smtp-relay.brevo.com 587 ``` A successful connection shows `Connection to smtp-relay.brevo.com 587 port [tcp/submission] succeeded!`. If it hangs, your provider is blocking the port. ## Configure Postfix as an external SMTP relay There are two paths: manual configuration or an automated script. Both produce the same result. ### Manual Postfix relayhost configuration The manual approach takes 5-10 minutes. You'll edit a few files and restart Postfix. If you're comfortable with the [essential Linux commands](/linux-commands), this is straightforward. **Step 1:** Install prerequisites (see the Prerequisites section above). **Step 2:** Edit the main Postfix configuration file: ```sh sudo nano /etc/postfix/main.cf ``` Add or modify these lines at the end of the file: ```sh compatibility_level = 3.11 relayhost = [smtp-relay.brevo.com]:587 smtp_sasl_auth_enable = yes smtp_sasl_password_maps = lmdb:/etc/postfix/sasl_passwd smtp_sasl_security_options = noanonymous smtp_tls_security_level = may smtp_tls_CAfile = /etc/ssl/certs/ca-certificates.crt inet_interfaces = loopback-only header_size_limit = 4096000 ``` A few things to note about this config: - **`smtp_sasl_security_options = noanonymous`**: this overrides the Postfix default of `noplaintext, noanonymous`. Without the override, PLAIN and LOGIN auth methods (which most providers use) would be rejected. We set `noanonymous` explicitly to allow PLAIN/LOGIN over TLS. - **`lmdb:`**: on Postfix 3.11+ (current stable), `lmdb:` is the forward-compatible table type. Older setups use `hash:`. Both work today, but `lmdb:` is the direction Postfix is heading. - **`inet_interfaces = loopback-only`**: for a send-only setup, this prevents Postfix from listening on public interfaces. Reduces attack surface. - **`smtp_tls_CAfile`**: ensures TLS certificate verification works on minimal installs where CA certs might not be in the default path. Replace `smtp-relay.brevo.com` with your provider's SMTP server. **Step 3:** Create the SASL password file: ```sh sudo nano /etc/postfix/sasl_passwd ``` Add this line: ```sh [smtp-relay.brevo.com]:587 your_username:your_password ``` Replace with your actual SMTP credentials. **Step 4:** Generate the lookup table: ```sh # Postfix 3.11+ (lmdb): sudo postmap lmdb:/etc/postfix/sasl_passwd # Older Postfix (hash): # sudo postmap hash:/etc/postfix/sasl_passwd ``` **Step 5:** Secure the credential files: ```sh sudo chown root:root /etc/postfix/sasl_passwd /etc/postfix/sasl_passwd.db sudo chmod 0600 /etc/postfix/sasl_passwd /etc/postfix/sasl_passwd.db ``` **Step 6:** (Optional) Rewrite the sender address for all outgoing mail. This is useful when your system sends mail as `root@hostname` but you want everything to come from a real address. ```sh sudo nano /etc/postfix/sender_canonical ``` Add: ```sh /.+/ your_email@example.com ``` Create the header checks file: ```sh sudo nano /etc/postfix/smtp_header_checks ``` Add: ```sh /From:.*/ REPLACE From: your_email@example.com ``` Enable the rewriting: ```sh sudo postconf -e 'sender_canonical_classes = envelope_sender, header_sender' sudo postconf -e 'sender_canonical_maps = regexp:/etc/postfix/sender_canonical' sudo postconf -e 'smtp_header_checks = regexp:/etc/postfix/smtp_header_checks' ``` **Step 7:** Set the mailname and restart: ```sh echo "yourdomain.com" | sudo tee /etc/mailname sudo systemctl restart postfix ``` **Verify:** Run `postfix check`. It should return no errors. Then `systemctl status postfix` should show `active (exiting)`. ### Using the automated Postfix setup script The script handles everything in one go: package installation, configuration, credential setup, optional sender rewriting, and restart. I put it together for repeatable deployments across multiple VPS instances. **Step 1:** Download the script: ```sh curl -sSL https://utils.bitdoze.com/scripts/postfix-setup.sh -o postfix-setup.sh ``` **Step 2:** Make it executable and run: ```sh chmod +x postfix-setup.sh bash postfix-setup.sh ``` **Step 3:** Follow the prompts. The script will ask for: - Your SMTP username - Your SMTP password - The domain you're using with your SMTP provider - A sender email address (press Enter to skip) - Your Postfix hostname - Your SMTP server address and port (e.g., `[smtp-relay.brevo.com]:587`) **Example output:** ```sh root@cloud:/var/log# bash postfix-setup.sh [2024-09-18 06:04:42] Step 1: Make sure you have already set up your domain with your SMTP provider and added any necessary DNS records (like SPF, DKIM, and CNAME). Enter your SMTP Username: bitdoze1@gmail.com Enter your SMTP Password: Enter the domain you are using with your SMTP provider (e.g. example.com): bitdoze.ro Enter the sender email address (optional, press Enter to skip): Enter your Postfix hostname (e.g. yourdomain.com): bitdoze.ro Enter your SMTP server with port (e.g. [smtp.provider.com]:587): [smtp-relay.brevo.com]:587 [2024-09-18 06:05:20] Step 2: Updating system and installing Postfix... [2024-09-18 06:05:23] Step 3: Configuring Postfix... [2024-09-18 06:05:23] Backed up /etc/postfix/main.cf to /etc/postfix/main.cf.bak [2024-09-18 06:05:23] Step 4: Creating /etc/postfix/sasl_passwd file with SMTP credentials... [2024-09-18 06:05:23] Backed up /etc/postfix/sasl_passwd to /etc/postfix/sasl_passwd.bak [2024-09-18 06:05:23] Securing /etc/postfix/sasl_passwd and creating hash... [2024-09-18 06:05:25] Step 5: Configuring sender address settings... [2024-09-18 06:05:25] Resetting sender address configuration... [2024-09-18 06:05:25] Step 6: Configuring /etc/mailname... [2024-09-18 06:05:25] Backed up /etc/mailname to /etc/mailname.bak [2024-09-18 06:05:25] Step 7: Restarting Postfix... postfix/postfix-script: refreshing the Postfix mail system [2024-09-18 06:05:27] All done! Postfix has been configured with your SMTP settings. ``` **Verify:** After the script completes, run `systemctl status postfix`. It should show `active`. Send a test email (see the testing section below) to confirm delivery. ### What the script does The script automates these steps: 1. **Backs up existing config files**: creates `.bak` copies of `main.cf`, `sasl_passwd`, and `mailname` before touching them. If something goes wrong, you can roll back. 2. **Installs required packages**: runs `apt update` and installs `mailutils` (and `libsasl2-modules` if the script has been updated). 3. **Configures main.cf**: sets relayhost, SASL auth, TLS, and other relay settings. 4. **Creates SASL credentials**: writes the `sasl_passwd` file, sets permissions to `0600`, and generates the lookup table with `postmap`. 5. **Optional sender rewriting**: if you provide a sender email, sets up `sender_canonical` and `smtp_header_checks` so all outgoing mail uses that address. 6. **Restarts Postfix**: applies the new configuration. Throughout the process, the script logs each step and checks for errors. If anything fails, it stops and reports the issue rather than continuing with a broken config. YouTube embed of the one-click setup walkthrough: ## Port 465 with implicit TLS (optional) Port 587 with STARTTLS is the most common and well-tested setup. But many providers (including Brevo) also support **port 465 with implicit TLS** (sometimes called SMTPS or wrappermode). RFC 8314 now recommends port 465 for implicit TLS alongside 587 for STARTTLS. To use port 465, change your relayhost and add one line to `main.cf`: ```sh relayhost = [smtp-relay.brevo.com]:465 smtp_tls_wrappermode = yes ``` That's it. The rest of the config stays the same. Port 587 with STARTTLS is the most widely tested combination. Port 465 works on modern Postfix versions, but some older distributions have quirks with wrappermode. Default to 587 unless your provider specifically requires 465. ## Testing and verifying your Postfix SMTP relay After configuration (whether manual or script), verify everything works before trusting it for real email. ### Send a test email ```sh echo "Postfix relay test" | mail -s "Test Email" recipient@example.com ``` With a custom sender address: ```sh echo "Postfix relay test" | mail -s "Test Email" -r sender@yourdomain.com recipient@example.com ``` Replace `recipient@example.com` with an address you can check. ### Check the mail log Watch the log in real time while sending: ```sh tail -f /var/log/mail.log ``` Or check recent entries: ```sh tail -100 /var/log/mail.log ``` A successful delivery looks like: ```sh Jul 17 10:30:45 hostname postfix/smtp[12345]: 1AB2C3D4E5F: to=, relay=smtp-relay.brevo.com[1.2.3.4]:587, delay=0.8, delays=0.02/0.00/0.5/0.28, dsn=2.0.0, status=sent (250 2.0.0 OK 1234567890abcdef) ``` The key is `status=sent`. If you see `status=bounced`, `status=deferred`, or `status=failed`, read the error message that follows. It usually tells you exactly what's wrong. You can also use `journalctl`: ```sh journalctl -u postfix -f ``` ### Verify deliverability 1. **Send to multiple domains**: test with Gmail, Outlook, and Yahoo. Each has different spam filters. 2. **Check spam folders**: even with correct config, new domains/IPs sometimes land in spam until reputation builds up. 3. **Use mail-tester.com**: send a test email to the address they give you, then check their score. They'll flag SPF/DKIM/DMARC issues, blacklists, and content problems. 4. **Check IP reputation**: use MXToolbox to verify your VPS IP isn't on any blacklists (this is separate from your SMTP provider's reputation). ## Troubleshooting common Postfix SMTP relay errors This is the section I wish existed when I first set up Postfix relay. Here are the errors you're most likely to hit. ### "No worthy mechs found": SASL authentication failure **Symptom:** In `/var/log/mail.log`: ```sh warning: SASL authentication failure: No worthy mechs found ``` **Cause:** `libsasl2-modules` is not installed. This is the most common failure for new Postfix relay setups. **Fix:** ```sh sudo apt install -y libsasl2-modules sudo systemctl restart postfix ``` Verify SASL mechanisms are available: `postconf -m | grep sasl` ### "Authentication failed": wrong credentials **Symptom:** `SASL authentication failed` or `authentication failed` in the mail log. **Cause:** Incorrect username or password in `/etc/postfix/sasl_passwd`. Some providers (Brevo, Gmail) require app-specific passwords or SMTP keys, not your regular login password. **Fix:** 1. Verify your credentials by logging into your provider's dashboard 2. Check the sasl_passwd file: `sudo cat /etc/postfix/sasl_passwd` 3. Regenerate the lookup table: `sudo postmap lmdb:/etc/postfix/sasl_passwd` 4. Restart: `sudo systemctl restart postfix` ### "Connection timed out": blocked SMTP ports Hetzner, OVH, Contabo, and many other providers block outbound port 587 and 465 by default. You'll need to open a support ticket asking them to unblock port 587 for your server. Some providers require you to have a paid account for a certain period before they'll unblock SMTP. **Symptom:** `Connection timed out` or `Network is unreachable` in the mail log. **Cause:** Your VPS provider is blocking outbound SMTP traffic. **Fix:** Open a support ticket with your hosting provider asking to unblock port 587. To verify, test the connection: `nc -zv smtp-relay.brevo.com 587` ### "Relay access denied" **Symptom:** `relay access denied` in the mail log. **Cause:** The `relayhost` directive is missing or misconfigured, or SASL authentication isn't working (Postfix tries to deliver directly and gets rejected by the recipient server). **Fix:** Verify `relayhost` is set in `/etc/postfix/main.cf`: ```sh postconf relayhost ``` Should return something like `[smtp-relay.brevo.com]:587`. If empty, add it and restart Postfix. ### Emails landing in spam **Symptom:** Emails are sent successfully (`status=sent` in the log) but recipients don't see them in their inbox. **Cause:** Missing or incorrect SPF, DKIM, or DMARC DNS records. This is a DNS configuration issue, not a Postfix issue. **Fix:** 1. Log into your SMTP provider's dashboard and check domain authentication status 2. Verify SPF, DKIM, and DMARC records exist in your domain's DNS zone 3. Use mail-tester.com to get a detailed deliverability report 4. Check MXToolbox for DNS and blacklist issues ## Conclusions Configuring Postfix to relay through an external SMTP server is the reliable path for VPS email delivery. You get the flexibility of a local MTA without the pain of managing your own mail server reputation. Brevo remains my default recommendation for free-tier needs. 300 emails/day covers most workloads. Always test thoroughly before relying on the setup for production email. Check the mail log, verify deliverability across multiple providers, and make sure your DNS records are solid. If you also need to [send WordPress emails via SMTP](/send-emails-in-wordpress-zoho-smtp-fluentsmtp), the same SMTP provider credentials work with plugins like FluentSMTP. For next steps on [securing your server](/bsi-security-report-docker-ufw), see the Docker security guide, or [harden your Linux server](/secure-ssh-server-linux) with the SSH hardening walkthrough.

Sink Install: Free Self-Hosted Link Shortener (2026 Guide)

Thu, 06 Aug 2026 00:00:00 GMT

import YouTubeEmbed from "../../components/widgets/YouTubeEmbed.astro"; import Button from "../../components/widgets/Button.astro"; import Notice from "../../components/widgets/Notice.astro"; import ListCheck from "../../components/widgets/ListCheck.astro"; import Accordion from "../../components/widgets/Accordion.astro"; import { Picture } from "astro:assets"; import img1 from "../../assets/images/24/09/ai-analytics.png"; import img2 from "../../assets/images/24/09/sink-ui.png"; [Sink](https://github.com/miantiao-me/Sink) is an open-source, free self-hosted link shortener that runs entirely on Cloudflare's edge network. Originally created by ccbikai, the project has moved to the `miantiao-me` GitHub organization and now has around 7,000 stars. With v0.3.0, the storage layer switched from KV to Cloudflare D1 as the primary database, a breaking change that makes the old installation guide outdated. This article covers deploying Sink on Cloudflare Workers with the current D1-based architecture, updated for 2026. ## What is Sink? Sink is a self-hosted link shortener that runs on Cloudflare Workers. It uses D1 (Cloudflare's SQL database) for permanent link storage and KV as a write-through read cache for fast redirects. The Cloudflare free tier is enough for personal and small-team use. No VPS, no Docker containers, no server to maintain. The project is now at v0.3.0 (latest stable: v0.2.11 if you want the pre-D1 version). The repo lives at [github.com/miantiao-me/Sink](https://github.com/miantiao-me/Sink). It's licensed under AGPL-3.0. ## Why choose a free self-hosted link shortener? Hosted link shorteners like Bitly start at $8/month. Dub.co has a free tier but limits features behind a paywall. Short.io caps you on the free plan. Sink costs nothing if you stay within Cloudflare's free tier limits. The self-hosting angle matters: you own your data, there's no vendor lock-in, and you get analytics, AI-powered slug generation, and features like password protection and geo-based routing. All included, no upsells. If you're building a home server with [Docker containers](/docker-containers-home-server), Sink is a lightweight addition to your self-hosted stack, though it runs on Cloudflare, not on your server. For business use, [Sink complements other self-hosted tools](/docker-containers-business) in your stack. The same author offers [S.EE](https://s.ee), a managed link platform with 180,000+ users, A/B testing, link-in-bio pages, and commercial plans. The Sink README explicitly recommends S.EE for professional/business needs. ## What's new in Sink (2024-2026) Sink has added a lot since the original version. Here are the highlights: - **D1 replaces KV as primary database** (v0.3.0): KV is now only a redirect cache - **Link tags, filtering, and sorting** (v0.3.0) - **Click webhooks with HMAC signatures** (v0.2.11): Dub-style webhook payloads - **Cloudflare Access auth** (v0.2.11): alternative to `NUXT_SITE_TOKEN` - **Duplicate URL detection** (v0.2.11) - **Link check dashboard** (v0.2.10): batch broken-link detection with CSV export - **Country/geo-based redirection** (v0.2.9): route visitors by Cloudflare-detected country - **AI OpenGraph generation** (v0.2.9): generate OG metadata from page content - **UTM parameter builder** (v0.2.8): built-in with live preview - **Password protection and link cloaking** (v0.2.6): per-link password gate, full-screen iframe masking - **Device-based redirection** (v0.2.3): route iOS/Android/Desktop differently - **OpenGraph customization** (v0.2.3): per-link OG title, description, image - **Real-time analytics** (v0.2.4+): 3D WebGL globe, 10-second polling event log - **QR code generation**: built-in for all short links - **Import/export**: JSON for links, CSV for analytics - **Multi-language UI**: 10+ languages The ecosystem has grown too: there's now a Chrome extension ("Sink Quick Shorten"), a Raycast extension, an iOS app, and Apple Shortcuts support. ## Key features ### AI-powered slug generation Sink uses Workers AI with the `@cf/qwen/qwen3-30b-a3b-fp8` model by default. When creating a link, you can let AI suggest a relevant, catchy slug based on the destination URL. It saves time when you're shortening links in bulk. ### Password protection and link cloaking Set a per-link password to gate access, useful for sharing internal docs or time-sensitive content. Link cloaking renders the destination inside a full-screen iframe, masking the target URL. Note: cloaking only works on sites that allow iframe embedding. ### Device and geo-based redirection Route visitors to different URLs based on their device (iOS/Android/Desktop) or country (detected by Cloudflare). This is handy for app store links: send iPhone users to the App Store, Android users to Google Play, desktop users to a landing page. ### Advanced analytics and link health monitoring Sink tracks clicks with geographic data, referrer information, and device breakdowns rendered on a 3D WebGL globe. The link check dashboard (v0.2.10) batch-verifies destination URL reachability and exports broken links as CSV. You can also export access analytics as CSV. Sink includes built-in analytics, but if you need website-wide analytics beyond link clicks, [Plausible is a great self-hosted companion](/install-plausible-analytics). ### Webhooks, API, and integrations Click webhooks (v0.2.11) send Dub-style payloads to a configured URL with optional HMAC signatures. Every Sink instance exposes OpenAPI docs at `/docs/scalar`, making it easy to integrate with automation tools and MCP proxies. The Chrome extension, Raycast extension, iOS app, and Apple Shortcuts integrations make Sink practical for daily use. ## Technologies powering Sink Sink's tech stack has evolved since the original version: | Component | Role | |---|---| | **Nuxt 4** | Frontend framework (upgraded from Nuxt.js) | | **Cloudflare D1** | Primary database, stores all links (NEW in v0.3.0) | | **Cloudflare Workers KV** | Write-through read cache for fast redirects | | **Drizzle ORM** | Database access layer for D1 | | **Cloudflare R2** | Optional: automatic backups and social images | | **Shadcn-vue + Tailwind CSS** | UI components and styling (unchanged) | D1 stores your links permanently. KV caches them for fast redirects. Both are required. When you create a link, it writes to D1 first, then to KV. Redirects read from KV (fast) and fall back to D1 if the cache misses. This is a different architecture from the original article where KV was the only storage. ## Deploy Sink on Cloudflare Workers (recommended) Cloudflare Workers is the recommended deployment method. Pages still works but is deprecated. This section walks through the full setup. The video above was recorded before the D1 migration. Follow the written steps below for the current deployment process. ### Prerequisites - Cloudflare account (free tier is fine) - GitHub account (to fork the repository) - A domain added to Cloudflare (for custom short URLs) - Cloudflare API token with Account > Account Analytics > Read permission (create at Profile > API Tokens) ### Step 1: Fork the repository Go to [github.com/miantiao-me/Sink](https://github.com/miantiao-me/Sink) and click **Fork**. This creates your own copy under your GitHub account. If you previously forked `ccbikai/Sink`, GitHub redirects still work, but update your bookmarks and any CI references to the new URL. ### Step 2: Create a Cloudflare D1 database Without a D1 database, Sink cannot store links. This didn't exist when the original article was written. 1. Go to **Cloudflare Dashboard** > **D1** > **Create database** 2. Name it `sink` 3. Copy the **database ID** from the database details page. You'll need it later ### Step 3: Create a KV namespace 1. Go to **Cloudflare Dashboard** > **Workers & Pages** > **KV** > **Create a namespace** 2. Name it `sink` 3. Copy the **namespace ID**. You'll need it in the next step ### Step 4: Deploy with Workers Git integration 1. Go to **Cloudflare Dashboard** > **Workers & Pages** > **Create** 2. Select **Workers** (not Pages) 3. Click **Connect to Git** and authorize GitHub 4. Select your forked Sink repository and the `master` branch 5. Set **Build command**: `pnpm build` 6. Set **Deploy command**: `pnpm deploy:worker` 7. Click **Save and Deploy** ### Step 5: Configure build variables and bindings After the first deployment, configure two sets of settings. **Build variables** (Settings > Variables and Secrets): | Variable | Value | |---|---| | `DEPLOY_D1_DATABASE_ID` | Your D1 database ID from Step 2 | | `DEPLOY_KV_NAMESPACE_ID` | Your KV namespace ID from Step 3 | **Runtime bindings** (Settings > Bindings): | Binding Name | Type | Resource | |---|---|---| | `DB` | D1 Database | `sink` | | `KV` | KV Namespace | `sink` | | `ANALYTICS` | Analytics Engine | Dataset: `sink` | | `R2` | R2 Bucket | Optional: name: `sink` | | `AI` | Workers AI | Optional: for AI features | Without the D1 `DB` binding, you'll get errors when creating links. This is the most common deployment mistake since v0.3.0. **Environment variables** (Settings > Variables and Secrets): | Variable | Value | |---|---| | `NUXT_SITE_TOKEN` | Your admin password (minimum 8 characters) | | `NUXT_CF_ACCOUNT_ID` | Your Cloudflare account ID (visible in the dashboard URL) | | `NUXT_CF_API_TOKEN` | API token with Account Analytics Read permission | ### Step 6: Complete storage setup (first run) After deployment, you must initialize the database. This is a one-time step. 1. Open `https://your-domain/dashboard` 2. Log in with your `NUXT_SITE_TOKEN` 3. Navigate to **Links** This triggers the storage initialization. Until you do this, the API returns HTTP 423 (Storage not ready). If you skip this step, link creation will fail. ### Step 7: Add your custom domain 1. Go to **Workers & Pages** > your project > **Settings** > **Domains & Routes** 2. Click **Add custom domain** 3. Enter your domain (e.g., `go.yourdomain.com`) 4. Cloudflare handles DNS and TLS automatically Verify the domain is active: ```bash curl -I https://your-domain/test-slug ``` You should get a 301 or 302 redirect (even if the slug doesn't exist yet, the worker is responding). ## Deploy Sink on Cloudflare Pages (deprecated) Use Workers (above) for new installations. The steps below are for existing Pages users who want to upgrade. Pages deployment still works but requires extra configuration: 1. Enable the `nodejs_compat` compatibility flag in your Pages project settings (this wasn't required before) 2. Add `CLOUDFLARE_API_TOKEN` with D1 Edit permission and `CLOUDFLARE_ACCOUNT_ID` as environment variables. The `postbuild` script runs D1 migration automatically on `master` branch builds 3. All other bindings (DB, KV, ANALYTICS, R2, AI) still apply Already hosting an [Astro blog on Cloudflare](/deploy-astrojs-cloudflare)? Sink fits alongside your existing Cloudflare projects, though Workers is the simpler path now. ## Post-deployment: verification and troubleshooting ### Verify your deployment - Open `https://your-domain/dashboard` — should show the login screen - Log in with `NUXT_SITE_TOKEN` - Create a test short link — verify the redirect works by visiting it in a browser - Check the analytics page — visit your test link from a different device/browser, confirm the click appears - Visit `/docs/scalar` — the API documentation should be accessible ### Common issues and fixes **Cause:** Storage not initialized, or the `DB` and `KV` bindings are missing. **Fix:** Open your Sink dashboard, navigate to Links once to trigger initialization. If that doesn't help, check that both `DB` (D1) and `KV` bindings are configured in Workers settings. Redeploy after adding bindings. **Cause:** Missing `ANALYTICS` binding, wrong dataset name, or API token lacks the right permission. **Fix:** Ensure the `ANALYTICS` binding exists with dataset name `sink`. Verify your `NUXT_CF_API_TOKEN` has "Account > Account Analytics > Read" permission. Redeploy after changes. **Cause:** Slugs are case-insensitive by default. **Fix:** Set `NUXT_CASE_SENSITIVE=true` in environment variables and redeploy. Note that this means `Go/Link` and `go/link` will be different URLs. **Cause:** The target site blocks iframe embedding via `X-Frame-Options` or `Content-Security-Policy` headers. **Fix:** Cloaking only works on sites that allow being embedded. Most major sites (Google, GitHub) block it. Test with a site you control. **Cause:** Browser or CDN caching the redirect response. **Fix:** Set `NUXT_REDIRECT_NO_STORE=true` in environment variables to prevent caching. You can also adjust `NUXT_LINK_CACHE_TTL` (default: 60 seconds) to control KV cache duration. **Cause:** Upgrading from a version that stored links only in KV. **Fix:** Deploy v0.3.0 with your original KV namespace still bound. Then open Dashboard > Links — this triggers the KV-to-D1 migration automatically. The API returns HTTP 423 until migration completes. Existing links continue working during migration as long as the original KV namespace stays bound. ## Advanced configuration options Sink exposes many environment variables for fine-tuning behavior. Changing any of these requires a redeploy on Workers. | Variable | Default | Purpose | |---|---|---| | `NUXT_HOME_URL` | empty | Redirect `/` to a URL | | `NUXT_NOT_FOUND_REDIRECT` | empty | Custom 404 destination | | `NUXT_REDIRECT_STATUS_CODE` | `301` | Redirect HTTP code (301/302/307/308) | | `NUXT_LINK_CACHE_TTL` | `60` | KV cache TTL in seconds | | `NUXT_REDIRECT_WITH_QUERY` | `false` | Forward visitor query params to destination | | `NUXT_CASE_SENSITIVE` | `false` | Preserve slug case | | `NUXT_DISABLE_BOT_ACCESS_LOG` | `false` | Drop bot traffic from analytics | | `NUXT_DISABLE_AUTO_BACKUP` | `false` | Disable scheduled R2 backups | | `NUXT_AI_MODEL` | `@cf/qwen/qwen3-30b-a3b-fp8` | Workers AI model for slug suggestions | | `NUXT_WEBHOOK_URL` | empty | Click webhook URL | | `NUXT_WEBHOOK_SECRET` | empty | Webhook HMAC secret (`whsec_` prefix) | | `NUXT_CF_ACCESS_TEAM_DOMAIN` | empty | Cloudflare Access team domain | | `NUXT_CF_ACCESS_AUD` | empty | Cloudflare Access AUD | | `NUXT_PUBLIC_SLUG_DEFAULT_LENGTH` | `6` | Auto-generated slug length | | `NUXT_API_CORS` | empty | Enable CORS for `/api/**` | Full reference: [docs.sink.cool/configuration](https://docs.sink.cool/configuration/) To undo a change: remove the variable and redeploy. ## Backups and production notes If you configured the R2 binding (Step 5), Sink runs automatic backups on a schedule. Disable with `NUXT_DISABLE_AUTO_BACKUP=true`. For broader R2 backup strategies, see how to [configure Dokploy backups with Cloudflare R2](/dokploy-backups-cloudflare-r2) — the R2 setup process is similar. **Cloudflare free tier limits (relevant to Sink):** | Product | Free limit | Notes | |---|---|---| | Workers requests | 100,000/day | Resets at 00:00 UTC | | D1 rows read | 5 million/day | Resets at 00:00 UTC | | D1 rows written | 100,000/day | Resets at 00:00 UTC | | D1 storage | 5 GB total | Sum of all databases on your account | | KV reads | 100,000/day | | | KV writes | 1,000/day | | | R2 storage | 10 GB | | Sink runs free on Cloudflare's free tier for personal use. Heavy traffic (thousands of links, millions of clicks) may require the Workers Paid plan at $5/month, with D1 overage at $0.001 per million rows read. For most people shortening links for social media or email campaigns, the free tier is more than enough. Every Sink instance also exposes OpenAPI docs at `/docs/scalar`, which is useful for automation and [AI agent integration](/ai-docker-deploy-skill). ## Sink vs alternatives | Feature | Sink | Dub.co | Bitly | Short.io | |---|---|---|---|---| | Self-hosted | Yes | Yes (open-core) | No | No | | Cost | Free (Cloudflare) | Free tier + paid | From $8/mo | Free tier + paid | | AI slug generation | Yes | No | No | No | | Geo/device routing | Yes | Yes | Yes (paid) | Yes (paid) | | Password protection | Yes | No | No | No | | Cloudflare-native | Yes | No | No | No | Sink's main advantage is that it runs entirely on Cloudflare's free tier with no server to manage. If you're managing a broader self-hosted setup, you can [compare the best server panels](/best-self-hosted-panels) or check out [Coolify](/coolify-install-heroku-alternative) as a self-hosted PaaS. If you use [Dokploy for self-hosting](/dokploy-install), Sink is one more service you can run alongside — though on Cloudflare rather than your VPS. ## Extending Sink: apps and integrations Sink has several clients and integrations: - **Chrome Extension**: "Sink Quick Shorten" lets you right-click any URL to shorten it (Chrome Web Store) - **Raycast Extension**: "Sink Short Links Manager" for macOS power users (Raycast Store) - **iOS App**: Native iPhone app on the App Store - **Apple Shortcuts**: macOS and iOS automation integration - **API**: OpenAPI docs at `/docs/scalar`, MCP support via OpenAPI proxy These make Sink far more practical than a dashboard-only tool. You can shorten links from your browser, phone, or terminal without opening the dashboard. ## Conclusion Sink started as a simple Cloudflare KV-based shortener and is now a full link management platform. The v0.3.0 D1 migration makes it a proper database-backed application while keeping the zero-server, zero-cost deployment model. Password protection, geo routing, webhooks, and the extension ecosystem (Chrome, Raycast, iOS, Apple Shortcuts) make it a solid choice for anyone who wants link shortening without monthly fees or vendor lock-in. If you're building out your self-hosted stack, Sink pairs well with [Docker containers for your home server](/docker-containers-home-server) — one runs on your infrastructure, the other runs free on Cloudflare's edge.

BSI Security Report from Hetzner: How I Secured My Docker Server

Wed, 05 Aug 2026 00:00:00 GMT

import Notice from "../../components/widgets/Notice.astro"; import ListCheck from "../../components/widgets/ListCheck.astro"; import Accordion from "../../components/widgets/Accordion.astro"; A few days ago I got an email from [Hetzner](https://www.hetzner.com/) that started like this: > We have received a notification from the German Federal Office for Information Security (BSI) for (the IP address of) a server you have with us. No, I hadn't been hacked. No, BSI wasn't accusing me of anything. This is routine: BSI runs security scanners across the German IP space, finds open ports and exposed services, and notifies the hosting provider. The provider forwards the report to the customer. The email even says you don't need to respond, and that the issue is "usually fairly easy to secure." There was one catch: the original report (with the exact port and CVE) was an attachment I had to dig out of the email chain. I didn't want to wait for it, so I audited the server myself. It took about 20 minutes, and it turned out the BSI scanner had picked a good target: the box was wide open. Here's the full story: how I audited the server, the ufw rule set that fixed it, the gotcha that briefly broke my reverse proxy (and the single rule that fixed that), and the defense-in-depth steps I took after. If you run a VPS with Docker, run this audit today. ## What a BSI report is (and what it isn't) The [BSI](https://www.bsi.bund.de/) is the German Federal Office for Information Security. Its computer emergency response team, CERT-Bund, scans German IP ranges for known vulnerabilities and exposed services: open databases, unauthenticated admin panels, outdated software with public CVEs. When they find something on an IP owned by a German provider, they send a report and the provider forwards it to you. The important facts: - It is not an accusation, a threat, or a takedown notice. No abuse was involved. - You don't need to reply to BSI or your provider. - The report names the exact service, port, and/or CVE. Fix that and you're done. - The same scan runs against every German IP. The finding means someone out there verified your exposure was reachable. My report boiled down to one theme: **services listening on `0.0.0.0` with no firewall at all**. ## Step 1: Audit what's actually listening Three commands give you 95% of the picture. **1. Listening ports and their processes:** ```bash sudo ss -tulpn ``` **2. Docker containers and their published ports:** ```bash docker ps --format 'table {{.Names}}\t{{.Ports}}\t{{.Image}}' ``` **3. Firewall status:** ```bash sudo ufw status verbose ``` Here's what the first two revealed on my server: | Port | Service | Risk | |---|---|---| | 5432 | PostgreSQL (pgvector container) | 🔴 Exposed database | | 5532 | PostgreSQL (second instance) | 🔴 Exposed database | | 8055 | Directus CMS | 🔴 Exposed admin panel | | 9999, 18888 | Hindsight app | 🔴 Exposed app | | 6806 | Siyuan notes | 🔴 Exposed app | | 3552 | Arcane | 🟡 Exposed app | | 22 | SSH | 🟡 Root login + password auth | | 80, 443 | Caddy reverse proxy | 🟢 Intended | And the third command said `Status: inactive`. Nothing was filtering anything. Every published Docker port was reachable from the internet, and SSH was accepting root logins with passwords. How does this happen? It's the classic Docker pattern: you publish a port during setup so you can reach the service, then you put a reverse proxy (Caddy, Traefik, nginx) in front of it, and you never remove the `ports:` block. The proxy works, the app works, and nobody notices the raw ports are still bound to `0.0.0.0` — directly reachable from the internet, bypassing your proxy, its rate limiting, and any auth you added there. BSI notices. So does every botnet scanner that crawls German IP space. Within minutes of the firewall going up, I watched probes for exactly the flagged port get dropped. ## Step 2: Enable the firewall The fastest fix, and the one that closed every port at once, is ufw. This is the complete rule set that works for a Docker server with a public reverse proxy: ```bash sudo ufw default deny incoming sudo ufw default allow outgoing sudo ufw allow 22/tcp sudo ufw allow 80/tcp sudo ufw allow 443/tcp sudo ufw allow 443/udp sudo ufw allow from 172.16.0.0/12 comment 'Docker bridge networks -> host services' sudo ufw allow in on tailscale0 # only if you use Tailscale sudo ufw --force enable ``` Rule by rule: - `default deny incoming` — drop every new inbound connection that isn't explicitly allowed. Established connections stay alive, so your current SSH session survives the enable. - `22/tcp` — SSH. If you only ever SSH over Tailscale, skip this rule and let the `tailscale0` rule cover it. - `80/tcp` and `443/tcp` — your reverse proxy. This is the only door public traffic should use. - `from 172.16.0.0/12` — **do not skip this one**; it's the rule that keeps your Docker reverse proxy working. Explained in Step 3. - `in on tailscale0` — if you use Tailscale, the mesh can reach everything (including admin ports) without opening them to the internet. - `--force` — skip the "this may disrupt existing ssh connections" prompt. Then verify: ```bash sudo ufw status verbose ``` You want to see `Default: deny (incoming), allow (outgoing), deny (routed)` and your allow list below it. Recent ufw versions add a third default policy: `deny (routed)`. It applies to traffic forwarded through the host — which is exactly how Docker published ports work. So once ufw is active, published ports like `5432` are dropped from the internet even though they're still in your compose files. If you're on an older ufw and Docker ports still slip through, the fix is the `DOCKER-USER` iptables chain, covered in [how to fix Docker bypassing the firewall](/docker-bypasses-firewall/). ## Step 3: The gotcha — ufw killed my reverse proxy Here's the part that will save you a panic attack. My setup: an AI agent app running on the host on port 4111, with a Caddy container reverse-proxying a subdomain to it via `host.docker.internal:4111`. Standard pattern: the proxy lives in Docker, the backend lives on the host, and `host.docker.internal` (with `host-gateway` in `extra_hosts`) maps to the host's bridge gateway IP. After `ufw enable`, the subdomain came back with **502 Bad Gateway**. The Caddy container couldn't reach the host anymore. My first thought was that I'd misconfigured the firewall. I hadn't. The reason: `default deny incoming` does not only block the internet-facing interface. It drops **any new inbound connection to a host port, from any interface — including your Docker bridges**. The Caddy container connecting from `172.20.0.6` to the host gateway `172.17.0.1:4111` is "incoming" traffic as far as the host is concerned. Denied. Result: Caddy gets a refused connection and returns 502. The fix is the `172.16.0.0/12` rule from Step 2: ```bash sudo ufw allow from 172.16.0.0/12 comment 'Docker bridge networks -> host services' ``` Docker creates its bridge networks in `172.17.0.0/16` (`docker0`), `172.18.x`, `172.19.x`, `172.20.x`, and so on. `172.16.0.0/12` covers all of them. This only lets *your own containers* reach host ports — the internet can't spoof a source address on your private bridges, so nothing is reopened to the outside. Add the rule, re-check `ufw status verbose`, and your proxy is back. In my case the site returned 200 immediately after. ## Step 4: Verify — and watch the bots hit the wall Three checks. **1. Your public site still works** (run from the server itself so it goes out the public interface): ```bash curl -sk -o /dev/null -w 'HTTP %{http_code}\n' https://your-domain.com ``` Expect `200`. **2. The firewall state:** ```bash sudo ufw status verbose ``` **3. The satisfying part — the blocked probes:** ```bash sudo journalctl -k --no-pager | grep 'UFW BLOCK' | tail -10 ``` Within minutes of enabling ufw, the same kind of scanners that got me reported hit the wall: ``` kernel: [UFW BLOCK] IN=eth0 ... SRC=186.236.254.56 ... DPT=5432 SYN kernel: [UFW BLOCK] IN=eth0 ... SRC=178.128.214.243 ... DPT=23 SYN kernel: [UFW BLOCK] IN=eth0 ... SRC=91.230.168.148 ... DPT=50050 SYN ``` Port 5432 — exactly what the BSI report flagged — plus Telnet (23) and random ports. All dropped. That's the whole point: the exposure that got me reported is now invisible from the internet. ## Step 5: Defense in depth (do this too) The firewall closes the doors, but it's one `sudo ufw disable` away from opening them again. Make the exposure structural: **1. Unpublish ports in your compose files.** If only other containers need to reach a service, delete the `ports:` block entirely — containers talk over the Docker bridge using the service name. If you need host-local access (say, a local `psql`), bind to loopback instead of `0.0.0.0`: ```yaml ports: - "127.0.0.1:5432:5432" ``` **2. Harden SSH.** My server had `PermitRootLogin yes` and password authentication enabled. Since you have keys (confirm with `ls ~/.ssh/id_ed25519.pub`), add a drop-in config: ```bash sudo tee /etc/ssh/sshd_config.d/99-hardening.conf <<'EOF' PermitRootLogin prohibit-password PasswordAuthentication no KbdInteractiveAuthentication no EOF ``` Test before restarting, and keep a second SSH session open: ```bash sudo sshd -t && sudo systemctl restart ssh ``` A full walkthrough of key-based auth, fail2ban, and the rest is in the [SSH server hardening guide](/secure-ssh-server-linux/). **3. Put auth on anything that doesn't have it.** Admin panels and dev tools without their own login should sit behind basic auth at the proxy — same idea as [Traefik basic authentication](/traefik-basic-authentication/). **4. Add a behavior layer.** A firewall is static; tools like [CrowdSec](/crowdsec-secure-server/) watch logs and block offending IPs dynamically. Worth having on top. ## Checklist Here's the exact sequence I'd run on a fresh, previously-exposed server:

Audit with sudo ss -tulpn, docker ps, and sudo ufw status verbose
Write down which ports are supposed to be public (usually only 80 and 443)
Add the ufw rules from Step 2 before enabling — including the 172.16.0.0/12 Docker bridge rule
Enable with sudo ufw --force enable
Verify your site returns 200 and check journalctl -k | grep 'UFW BLOCK'
Remove or loopback-bind published ports in every compose file
Harden SSH (drop-in config, sudo sshd -t, restart, keep a second session)
Re-check from an external network that only 22, 80, 443 respond

## FAQ No. The notification is informational. Hetzner's forwarding email says so explicitly: "You do not need to send us, or the BSI, a response." If you want to confirm the exact finding, look for the ticket number (`CB-Report#...`) in the original report and use it if you ever contact [certbund@bsi.bund.de](mailto:certbund@bsi.bund.de). Do not reply to the sender address of the report email — it's unmonitored. On modern versions, yes. ufw's `deny (routed)` default policy applies to forwarded traffic, which is how Docker published ports reach containers, so they get dropped from the internet. On older ufw versions Docker's own iptables rules were evaluated before the firewall and could bypass it entirely — the `DOCKER-USER` chain fix is documented in [how to fix Docker bypassing the firewall](/docker-bypasses-firewall/). Either way, the belt-and-suspenders approach is to unpublish the ports in compose. Because `default deny incoming` also blocks container-to-host traffic over the Docker bridge. If your proxy container reaches a host service via `host.docker.internal:PORT`, the connection lands on the host's INPUT chain as incoming traffic and gets dropped. Allow the Docker bridge range with `sudo ufw allow from 172.16.0.0/12` and the proxy connects again. Yes. The firewall is one command away from being disabled (accidentally or during troubleshooting), and then every published port is public again. Removing or loopback-binding `ports:` in compose makes the exposure structural instead of incidental. It also removes the attack surface from the container's perspective — fewer reachable sockets, fewer CVEs that matter. ## The takeaway The BSI notification wasn't a threat — it was a free vulnerability scan, courtesy of the German government. The exposed services were my own doing: published Docker ports left behind after setup, no host firewall, and weak SSH defaults. Twenty minutes of auditing plus one firewall rule set closed all of it, and the one real surprise (the Docker bridge vs. ufw gotcha) is now a one-line rule in my standard server setup. If you're self-hosting on a VPS, spend those 20 minutes today. The scanners certainly will.

How To Deploy A Docker Compose App in Dokploy

Wed, 05 Aug 2026 00:00:00 GMT

import Button from "../../components/widgets/Button.astro"; import YouTubeEmbed from "../../components/widgets/YouTubeEmbed.astro"; import Notice from "../../components/widgets/Notice.astro"; import ListCheck from "../../components/widgets/ListCheck.astro"; import Accordion from "../../components/widgets/Accordion.astro"; import Tabs from "../../components/widgets/Tabs.astro"; import Tab from "../../components/widgets/Tab.astro"; import { Picture } from "astro:assets"; import img1 from "../../assets/images/24/08/dns-a-rec.png"; import img2 from "../../assets/images/24/08/dokploy-compose.png"; import img3 from "../../assets/images/24/08/dokploy-env.png"; import img4 from "../../assets/images/24/08/dokploy-domain-add.png"; [Dokploy](https://dokploy.com/) is an open-source, self-hostable Platform as a Service (PaaS) for deploying and managing applications with Docker and Traefik. It has 36,300+ GitHub stars and regular releases (currently at v0.29.x), and it's a free alternative to Vercel, Heroku, and Netlify. For comparisons, see [how Dokploy stacks up against Coolify and Kamal 2](/coolify-vs-dokploy-vs-kamal-2/) or our [self-hosted server panels roundup](/best-self-hosted-panels/). This guide walks through deploying any Docker Compose app in Dokploy. I'll use a Flowise AI + PostgreSQL stack as the running example, but the same workflow applies to any compose file. The video was recorded with an earlier Dokploy version. The workflow is the same, but the UI may look slightly different. The Domains tab is now the recommended method for configuring domains. ## Prerequisites Before you start, make sure you have everything in place: - A VPS running Linux (Ubuntu 22.04+ or Debian 12+). A Hetzner CX22 at ~€4.49/mo works well. You can get an [affordable VPS from Hetzner](https://go.bitdoze.com/hetzner) or a [budget VPS from Hostinger](https://go.bitdoze.com/hostinger-vps) - Dokploy installed and accessible at its dashboard URL. See our guide to [install and configure Dokploy on your VPS](/dokploy-install/) - Docker and Docker Compose v2 installed (the Dokploy installer handles this) - Ports 80 and 443 open on the VPS firewall (required for Traefik and Let's Encrypt) - A domain name with DNS access (to create an A record) - The Docker Compose file for the app you want to deploy If these ports are blocked by your firewall or cloud provider, Let's Encrypt certificate issuance will fail silently. Double-check before proceeding. Dokploy Cloud is available starting at $4.50/mo per server if you'd rather skip managing the infrastructure yourself. ## Flowise example: the Docker Compose file we'll deploy Here's the compose file we'll use throughout this guide. It runs Flowise AI with a PostgreSQL backend. This is a **clean version**: no Traefik labels and no `dokploy-network`. Dokploy handles networking and routing through the Domains tab or Isolated Deployments. ```yml services: flowise-db: image: postgres:16-alpine environment: POSTGRES_DB: ${POSTGRES_DB} POSTGRES_USER: ${POSTGRES_USER} POSTGRES_PASSWORD: ${POSTGRES_PASSWORD} volumes: - flowise-db-data:/var/lib/postgresql/data restart: unless-stopped healthcheck: test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER} -d ${POSTGRES_DB}"] interval: 5s timeout: 5s retries: 5 flowise: image: flowiseai/flowise:latest healthcheck: test: wget --no-verbose --tries=1 --spider http://localhost:${PORT} volumes: - flowiseai:/root/.flowise environment: DEBUG: false PORT: ${PORT} FLOWISE_USERNAME: ${FLOWISE_USERNAME} FLOWISE_PASSWORD: ${FLOWISE_PASSWORD} APIKEY_PATH: /root/.flowise SECRETKEY_PATH: /root/.flowise LOG_LEVEL: info LOG_PATH: /root/.flowise/logs DATABASE_TYPE: postgres DATABASE_PORT: 5432 DATABASE_HOST: flowise-db DATABASE_NAME: ${POSTGRES_DB} DATABASE_USER: ${POSTGRES_USER} DATABASE_PASSWORD: ${POSTGRES_PASSWORD} restart: on-failure:5 depends_on: flowise-db: condition: service_healthy entrypoint: /bin/sh -c "sleep 3; flowise start" volumes: flowiseai: driver: local flowise-db-data: driver: local ``` A few things to note: - **No `networks:` section**. Dokploy handles networking for you (via the Domains tab or Isolated Deployments). - **No `labels:` block**. Traefik routing is configured through the Domains tab, not in the compose file. - **No `container_name`**. Setting this in Dokploy causes issues with logs and metrics. Dokploy generates its own container names. - **No `version:` key**. Docker Compose v2 ignores it and may warn about it. If you're bringing your own compose file with `version: "3.8"`, just remove that line. - **`${VAR_NAME}` syntax**. Environment variables are referenced this way because Dokploy writes UI-defined vars to a `.env` file. More on this in the [environment variables section](#configuring-environment-variables-in-dokploy). For a refresher on compose syntax, see [essential Docker commands](/docker-commands/). The official docs have more examples at the [Dokploy Docker Compose docs](https://docs.dokploy.com/docs/core/docker-compose) and the [official example](https://docs.dokploy.com/docs/core/docker-compose/example). ## Point the domain to your server (DNS) Before deploying, point your domain or subdomain to the Dokploy server: - Add an A record in your DNS settings: - **Name**: the subdomain you want (e.g., `flowise` for `flowise.yourdomain.com`) - **Value**: your server's IP address Since Dokploy v0.22.0, the Domains tab includes built-in DNS validation. It checks whether your domain is correctly pointing to your server before you deploy. ## Method 1: using the Domains tab (recommended) This is Dokploy's recommended approach. You paste your compose file as-is, then configure the domain and port through the UI. Dokploy injects the Traefik labels and networking config automatically. For details on how Traefik works under the hood, see [how Traefik works as a reverse proxy in Docker](/traefik-proxy-docker/). ### Step 1: create the compose service 1. In the Dokploy dashboard, go to **Projects** and either create a new project or select an existing one. 2. Click **Create Service** → **Compose**. 3. Give it a name (e.g., `flowise`). 4. In **General**, select **Raw** as the source. 5. Paste the clean compose file from above. 6. Click **Save**. ### Step 2: add a domain 1. Go to the **Domains** tab. 2. Click **Add Domain**. 3. Fill in the fields: - **Domain**: enter your domain (e.g., `flowise.yourdomain.com`) - **Service Name**: select the service from the dropdown (e.g., `flowise`. This is the key from your compose file) - **Internal Port**: the port your app listens on inside the container (3000 for Flowise) - **Certificate Provider**: select **Let's Encrypt** for automatic HTTPS 4. Click **Save**. Dokploy will inject the required Traefik labels into the final compose file. You don't need to add them manually. ### Step 3: verify with Preview Compose After configuring your domain, click the **Preview Compose** button. This shows you the final compose file Dokploy will actually execute, with all injected Traefik labels, network config, and domain settings. This is a critical verification step. Check that: - The Traefik labels include your domain and the correct port - The `dokploy-network` has been injected (or an isolated network if you enabled that) - No unexpected changes were made to your services If Preview Compose shows the Traefik labels and your domain correctly, you're ready to deploy. ## Method 2: manual Traefik labels (advanced) For most users, Method 1 is sufficient. Use manual Traefik labels only when you need custom configuration: middleware (auth, rate limiting), multiple host rules, custom entrypoints, or non-standard TLS config. ### When to use manual labels - You need Traefik middleware (basic auth, rate limiting, custom headers) - You're routing multiple domains to a single service - You need custom entrypoints or TLS settings beyond what the Domains tab offers If none of these apply, stick with the Domains tab. ### Adding dokploy-network and Traefik labels With this approach, you modify the compose file to include the `dokploy-network` and Traefik labels: ```yml services: flowise: image: flowiseai/flowise:latest networks: - dokploy-network labels: - "traefik.enable=true" - "traefik.http.routers.flowiseai.rule=Host(`flowise.yourdomain.com`)" - "traefik.http.routers.flowiseai.entrypoints=websecure" - "traefik.http.routers.flowiseai.tls.certResolver=letsencrypt" - "traefik.http.services.flowiseai.loadbalancer.server.port=3000" # ... rest of your service config networks: dokploy-network: external: true ``` The Traefik label format: ```yml labels: - "traefik.enable=true" - "traefik.http.routers..entrypoints=websecure" - "traefik.http.routers..tls.certResolver=letsencrypt" - "traefik.http.routers..rule=Host(`app.yourdomain.com`)" - "traefik.http.services..loadbalancer.server.port=3000" ``` Replace `` with a unique identifier for your service, set the `Host()` to your domain, and set the port to whatever your app listens on internally. Every service that needs to communicate (e.g., the app and its database) must be on `dokploy-network`. For more on Traefik, see [Traefik FREE Let's Encrypt Wildcard Certificate](/traefik-wildcard-certificate/). ## Isolated Deployments (Advanced tab) Dokploy's Isolated Deployments feature is a third option for networking. When enabled, Dokploy: - Creates a **per-app isolated network** automatically - Connects Traefik to that isolated network - Eliminates the need to manually add `dokploy-network` to every service - Prevents service name conflicts when running multiple instances of the same app To enable it: go to the **Advanced** tab for your compose service and toggle **Isolated Deployments**. When using Isolated Deployments together with the Domains tab, your compose file can be used as-is. No `networks:` section, no labels, no modifications at all. Just paste and deploy. This is available for both Raw and Git provider compose services. See the [Utilities docs](https://docs.dokploy.com/docs/core/docker-compose/utilities) for details. ## Configuring Environment Variables in Dokploy The Flowise example uses `${VAR_NAME}` syntax throughout. Here's how that works in Dokploy. ### Understanding the .env file mechanism When you set environment variables in Dokploy's **Environment** tab, they are written to a `.env` file on the server. Your compose file must reference them with `${VAR_NAME}` syntax (or use `env_file: - .env`). This is different from application services, where vars are injected directly into containers. For the Flowise example, add these in the **Environment** tab: ```sh PORT=3000 POSTGRES_USER='user' POSTGRES_PASSWORD='pass' POSTGRES_DB='flowise' FLOWISE_USERNAME=bitdoze FLOWISE_PASSWORD=bitdoze ``` Environment variables set in the UI are NOT automatically injected into containers. You must reference them as `${VAR_NAME}` in your compose file or add `env_file: - .env` to your service definition. A few additional notes: - **Encryption at rest**: since v0.29.12, all environment variables are encrypted using AES-256-GCM. - **Shared variables**: Dokploy supports project-level (`${{project.VAR_NAME}}`) and environment-level (`${{environment.VAR_NAME}}`) shared variables. Useful when multiple services in the same project share credentials. See the [Variables docs](https://docs.dokploy.com/docs/core/variables). For a deeper dive on Docker environment variables, see [how Docker environment variables work with ARG and ENV](/docker-env-vars/). ## Deploy and verify your app After configuring your compose file, environment variables, and domain, it's time to deploy: 1. Go to **General** and click **Deploy**. 2. Switch to the **Deployments** tab to watch the build logs. 3. Wait for a "success" status. ### Checking deployment logs The Deployments tab shows real-time logs. A successful deploy ends with the containers running and Traefik routing traffic. If you see errors, the logs will point to the specific issue (wrong image tag, missing env var, port conflict, etc.). ### Verifying the app is running Once the deploy succeeds, verify it: ```sh curl -I https://flowise.yourdomain.com ``` You should get an `HTTP/2 200` response. The SSL certificate should be valid. Traefik issues it automatically via Let's Encrypt. It can take up to 10 seconds for Traefik to issue a Let's Encrypt certificate after the first deployment. If you get a certificate error immediately, wait a moment and try again. ## Backups for Docker Compose Apps Since v0.22.0 (May 2025), Dokploy supports database backups and volume backups for Docker Compose services. If you're running anything with persistent data, set this up early. ### Database backups (PostgreSQL) The Flowise example uses PostgreSQL. Dokploy can back up PostgreSQL, MariaDB, MySQL, and MongoDB databases within Docker Compose services. You configure this in the service's backup settings and point it to an S3-compatible destination. To set up Cloudflare R2 as your backup destination, see how to [configure Dokploy backups with Cloudflare R2](/dokploy-backups-cloudflare-r2/). ### Volume backups Dokploy can back up Docker named volumes to S3-compatible storage. This covers the `flowiseai` and `flowise-db-data` volumes in our example. Volume backups only work with named volumes (like `flowiseai:`), NOT bind mounts (like `./data:/app/data`). If your compose file uses bind mounts, you'll need a different backup strategy. See the [Volume Backups docs](https://docs.dokploy.com/docs/core/volume-backups) for configuration details. ## Troubleshooting common issues **Symptom**: browser shows "server not found" or Dokploy's DNS validation fails in the Domains tab. **Cause**: the A record isn't set, or the TTL hasn't expired yet. **Fix**: check your DNS record: ```sh dig flowise.yourdomain.com +short ``` This should return your server's IP. If it doesn't, verify the A record in your DNS provider. DNS propagation can take a few minutes to a few hours depending on your provider. **Symptom**: you get a 502 Bad Gateway or connection refused after deploying. **Cause**: the port configured in the Domains tab (or Traefik labels) doesn't match the port the app actually listens on inside the container. **Fix**: check your app's documentation for its default port. For Flowise, it's `3000` (controlled by the `PORT` env var). Make sure the **Internal Port** in the Domains tab matches. **Symptom**: the app starts but can't connect to its database (e.g., Flowise can't reach PostgreSQL). **Cause**: services are not on the same network. **Fix**: if you're using the Domains tab without Isolated Deployments, make sure all services that need to communicate are on `dokploy-network`. Or enable **Isolated Deployments** in the Advanced tab. Dokploy handles networking for you. Also verify that the service name in your connection string matches the key in the compose file (e.g., `flowise-db`, not `localhost`). **Symptom**: logs or metrics not showing in the Dokploy dashboard. **Cause**: `container_name` is set in the compose file. **Fix**: remove the `container_name` directive. Dokploy generates its own container names for tracking logs, metrics, and deployments. Setting it manually breaks this. For more debugging commands, see [essential Docker commands](/docker-commands/). To monitor your server after deployment, [set up server monitoring with Beszel and Uptime Kuma](/beszel-uptime-kuma/). ## Updating and maintaining your compose app After the initial deployment, you'll eventually need to update images, change environment variables, or modify the compose file. Dokploy makes this straightforward. Edit the config and redeploy. For the full update workflow (including how to handle image tags, rollbacks, and redeployments), see our guide on [updating your deployed Docker Compose apps in Dokploy](/dokploy-update-docker-compose/). ## Conclusions Deploying a Docker Compose app in Dokploy comes down to two approaches: 1. **Domains tab (recommended)**: paste your compose file as-is, configure the domain and port in the UI, and Dokploy handles the rest. No label editing, no network config. 2. **Manual Traefik labels (advanced)**: for when you need custom routing, middleware, or non-standard TLS setup. With Isolated Deployments enabled, you can take the cleanest path: zero modifications to your compose file. Paste, set environment variables, add a domain, and deploy. Don't skip backups. Set up database backups for any stateful service and volume backups for persistent data. It takes five minutes and saves you from data loss.

Nexterm Docker Install: Self-Hosted SSH, VNC & RDP Management

Wed, 05 Aug 2026 00:00:00 GMT

import Button from "../../components/widgets/Button.astro"; import { Picture } from "astro:assets"; import imag1 from "../../assets/images/24/09/nexterm-interface.png"; import imag2 from "../../assets/images/24/09/nexterm-add-server.png"; import Notice from "../../components/widgets/Notice.astro"; import ListCheck from "../../components/widgets/ListCheck.astro"; import Tabs from "../../components/widgets/Tabs.astro"; import Tab from "../../components/widgets/Tab.astro"; import Accordion from "../../components/widgets/Accordion.astro"; import YouTubeEmbed from "../../components/widgets/YouTubeEmbed.astro"; [Nexterm](https://nexterm.dev/) is an open-source, self-hosted server management platform for SSH, VNC, RDP, Telnet, SFTP, and FTP connections. At v1.2.2-BETA with nearly 5,000 GitHub stars and an MIT license, it's past the experimental stage. Production-capable, as long as you back up your data and pin versions. This guide covers a complete Nexterm Docker install using Docker Compose with Traefik reverse proxy, mandatory encryption key setup, and the security hardening you need before opening it to the network. ## What is Nexterm? Nexterm is a web-based server management dashboard that consolidates SSH, VNC, RDP, Telnet, SFTP, and FTP into a single interface. You deploy it as a Docker container, point your browser at it, and manage all your remote connections from one place. It supports OIDC SSO, LDAP, passkeys, 2FA, audit logging, session recordings, and role-based permissions (added in v1.2.2). There are desktop clients for Windows, macOS, and Linux, a mobile app for Android and iOS, and a CLI client (`nt`) for terminal purists. If you're comparing [self-hosted server management panels](https://www.bitdoze.com/best-self-hosted-panels/), Nexterm covers more protocols than most alternatives with a smaller resource footprint. It's also worth looking at [alternative SSH management tools like Termix](https://www.bitdoze.com/termix-self-host/) if you want something with a different architecture. ## Nexterm features

**Multi-protocol:** SSH, VNC, RDP, Telnet, SFTP, FTP, all from one dashboard
**Security:** 2FA (TOTP), Passkeys, OIDC SSO, LDAP, server-side encryption at rest, audit logging, role-based permissions, API keys
**Session management:** Split view, session recordings, session popout/live sharing, port tunneling, jump hosts
**Dynamic snippets and scripts:** Quick commands, scripts, SSH config import (fully implemented since v1.0.3)
**Desktop and mobile apps:** Desktop connector (Win/Mac/Linux), mobile app (Android/iOS) for VNC/RDP/SFTP, CLI client (`nt`)
**Server monitoring and AI:** Built-in server monitoring (v1.0.4+), AI integration for terminal assistance
**Infrastructure:** Organizations, tags, fuzzy search, internationalization, customizable themes, Nerd Fonts, Proxmox LXC/QEMU management

If you're building out a home lab, check [other self-hosted Docker containers for your home server](https://www.bitdoze.com/docker-containers-home-server/) for more ideas. ## How to install Nexterm with Docker Compose This uses the official `nexterm/aio` image (all-in-one: server + web client + engine). The old `germannewsmaker/nexterm` image is deprecated. If you're migrating from it, see the troubleshooting section below. ### Prerequisites

**VPS or home server:** Linux (Ubuntu 22.04+ / Debian 12+). Minimum 1 vCPU, 512 MB RAM, 2 GB disk. Use [Hetzner](https://go.bitdoze.com/hetzner), [Hostinger](https://go.bitdoze.com/hostinger-vps), or [Vultr](https://go.bitdoze.com/vultr) for a cheap VPS, or a [mini PC as a home server](https://www.bitdoze.com/best-mini-pc-home-server/)
**Docker and Docker Compose** installed. Use [Dockge for managing Docker Compose stacks](https://www.bitdoze.com/dockge-install/) if you want a web UI for your compose files
**Traefik (optional but recommended):** For HTTPS reverse proxy with automatic Let's Encrypt certificates. [Set up Traefik as a reverse proxy in Docker](https://www.bitdoze.com/traefik-proxy-docker/) or configure [Traefik with a free Let's Encrypt wildcard certificate](https://www.bitdoze.com/traefik-wildcard-certificate/)
**openssl:** required to generate the encryption key. Pre-installed on most Linux distros

Nexterm is lightweight. A 1 vCPU / 512 MB VPS is enough for managing dozens of connections. The AIO image is ~95 MB compressed. You do not need 8 CPUs and 16 GB RAM. That was for something else entirely. ### Step 1: Generate your encryption key Since v1.0.3, Nexterm requires server-side encryption of stored passwords and SSH private keys. The `ENCRYPTION_KEY` environment variable is **mandatory**. The container won't start without it. ```bash openssl rand -hex 32 ``` Example output: ``` a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2 ``` Copy this key. You'll paste it into the docker-compose file. If you lose the ENCRYPTION_KEY, all stored credentials become **unrecoverable**. Save it in a password manager. Never commit it to git. Docker secrets are also supported via `/run/secrets/encryption_key`. See how to [manage secrets securely with Docker Compose](https://www.bitdoze.com/docker-compose-secrets/). ### Step 2: Docker Compose configuration Create a `docker-compose.yml` file: ```yaml services: nexterm: image: nexterm/aio:latest environment: ENCRYPTION_KEY: "your-generated-key-here" volumes: - ./nexterm:/app/data networks: - traefik-net restart: always labels: - "traefik.enable=true" - "traefik.http.routers.nexterm.rule=Host(`nexterm.domain.com`)" - "traefik.http.routers.nexterm.entrypoints=websecure" - "traefik.http.routers.nexterm.tls.certresolver=letsencrypt" - "traefik.http.services.nexterm.loadbalancer.server.port=6989" networks: traefik-net: external: true ``` Replace `nexterm.domain.com` with your actual domain. The `traefik-net` network must already exist (create it with `docker network create traefik-net` if needed). The image is `nexterm/aio:latest`, the all-in-one package (server + web client + C-based engine) that replaces the deprecated `germannewsmaker/nexterm`. Paste the key from Step 1 into the `ENCRYPTION_KEY` variable. The volume `./nexterm:/app/data` persists all configuration, connections, and credentials. The Traefik labels route `nexterm.domain.com` traffic through Traefik with automatic Let's Encrypt TLS on port 6989. Nexterm distributes three images: `nexterm/aio` (all-in-one, recommended for most users), `nexterm/server` (server + web client only, needs external engine), and `nexterm/engine` (engine only, the C-based connection service). For 95% of setups, `aio` is the right choice. See the [official installation docs](https://docs.nexterm.dev/installation). ### Step 3: Start the container ```bash docker compose up -d ``` Verify it's running: ```bash docker compose ps docker compose logs nexterm ``` Run `docker compose logs nexterm` and look for the startup message confirming the server is listening on port 6989. If using Traefik, check the Traefik dashboard. The `nexterm` route should appear under your entrypoints. `docker compose ps` should show "Up" status. If the container exits immediately, the most common cause is a missing or malformed `ENCRYPTION_KEY`. Check the troubleshooting section below. ### Step 4: Access Nexterm and add your first connections Open `https://nexterm.domain.com` in your browser (or `http://your-server-ip:6989` if you skipped the reverse proxy). The first user you create becomes the admin. After logging in, add connections: 1. Click **Servers** in the sidebar 2. Create a folder (e.g., "Production" or "Home Lab") 3. Click the **+** button to add a new connection 4. Select the protocol (SSH, RDP, VNC, etc.), enter the host, port, and credentials 5. Save and double-click to connect ## Host network vs bridge network: which should you use? The official Nexterm docs recommend `network_mode: host` because it enables Wake-on-LAN and localhost connectivity to the Docker host. But host networking means Traefik Docker provider labels **won't work**. You'd need a file provider or a different reverse proxy. For most bitdoze readers with an existing Traefik stack, **bridge network (the setup above) is the practical choice**. Use host network only if you need Wake-on-LAN or localhost server access and don't use Traefik's Docker provider. **What you get:** Works with your existing Traefik Docker provider. Automatic TLS via Let's Encrypt labels. Clean integration with `traefik-net`. **What you lose:** No Wake-on-LAN support. No direct `localhost` connectivity to the Docker host from inside the container. Target servers must be reachable from the Docker bridge network. This is the setup in Step 2 above. **What you get:** Full access to the host's network stack. Wake-on-LAN works. Connect to `localhost` services on the host directly. **What you lose:** Traefik Docker labels don't function. You'll need to configure the reverse proxy via file provider, or use Nginx/Caddy with static config. Port 6989 is exposed on all host interfaces by default. ```yaml services: nexterm: image: nexterm/aio:latest environment: ENCRYPTION_KEY: "your-generated-key-here" network_mode: host restart: always volumes: - ./nexterm:/app/data ``` If using host network on a public VPS, restrict port 6989 with UFW/iptables or put it behind a VPN. If you're running Nexterm behind a Cloudflare Tunnel, ensure WebSocket proxying is enabled. Nexterm uses WebSocket for terminal sessions. Without it, you'll get a connection that immediately drops. See the [official reverse proxy docs](https://docs.nexterm.dev/reverse-proxy). ## Hardening and production notes Nexterm is still in beta (v1.2.x). Always back up your data directory before upgrading. Breaking changes between versions are possible. **Back up before upgrades.** Nexterm is beta. Data loss is possible between major version jumps. Always back up the `./nexterm` data directory before pulling a new image: ```bash docker compose down cp -r ./nexterm ./nexterm-backup-$(date +%Y%m%d) docker compose pull docker compose up -d ``` **ENCRYPTION_KEY management.** Store the key in a password manager. Never commit it to git or paste it in public forums. If you lose it, all stored credentials become unrecoverable. Docker secrets are supported. Mount at `/run/secrets/encryption_key` instead of using the environment variable. Learn more about how to [manage secrets securely with Docker Compose](https://www.bitdoze.com/docker-compose-secrets/). **Firewall.** If you're using host network mode on a public VPS, port 6989 is exposed directly on all interfaces. Use UFW or iptables to restrict access, or put Nexterm behind a reverse proxy. If you're running on Hetzner, read how to [secure your Docker server](https://www.bitdoze.com/bsi-security-report-docker-ufw/). For broader VPS hardening, [secure your VPS with CrowdSec](https://www.bitdoze.com/crowdsec-secure-server/). **Resource usage.** Nexterm typically runs under 200 MB RAM. The AIO image is ~95 MB compressed. It doesn't need much. A small VPS handles dozens of connections. **Regular updates.** Check [GitHub releases](https://github.com/gnmyt/Nexterm/releases) periodically. Use `nexterm/aio:latest` to auto-update on pull, or pin to a specific version like `nexterm/aio:1.2.2-BETA` for stability. ## Troubleshooting common issues **Symptom:** Container exits immediately after `docker compose up -d`. **Fix:** Ensure `ENCRYPTION_KEY` is set in the `environment` section of your docker-compose file. Check logs: ```bash docker compose logs nexterm ``` If you see encryption-related errors, regenerate the key with `openssl rand -hex 32` and restart. **Verify:** `docker compose ps` should show "Up" status after fixing. **Symptom:** Connection timeout or refused when trying to SSH to a target server. **Fix:** If using bridge network, verify the target is reachable from the container: ```bash docker compose exec nexterm ping target-ip ``` Check firewall rules on the target server. If the target is on a different network, the Docker bridge may not have a route to it. **Verify:** Check Nexterm logs for engine connection errors. **Symptom:** Connects to the remote server but displays a black screen. **Fix:** For RDP, try adjusting the security method. Since v1.2.2, Nexterm supports NLA and Kerberos configuration. For VNC, verify the VNC server is running and accepting connections on the target. Some VNC servers only accept connections from localhost by default. **Symptom:** Terminal connects but immediately disconnects. **Fix:** Nexterm requires WebSocket support. If using Nginx as your reverse proxy, add these headers: ```nginx proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection "upgrade"; ``` For Cloudflare, enable WebSocket proxying in the dashboard. See the [official reverse proxy docs](https://docs.nexterm.dev/reverse-proxy). **Symptom:** Switching to `nexterm/aio:latest` fails or data seems incompatible. **Fix:** Back up your `./nexterm` data directory first. Swap the image in docker-compose: ```yaml # old (deprecated) image: germannewsmaker/nexterm:1.0.1-OPEN-PREVIEW # new image: nexterm/aio:latest ``` If the container fails to start after the swap (encryption migration issues from pre-1.0.3 data), start fresh: delete the `./nexterm` directory and re-add your connections manually. The v1.2.1-BETA release notes warn that migration from very old versions may be unstable. ## Conclusion Nexterm at v1.2.2-BETA is a capable, lightweight, self-hosted server management platform. The Nexterm Docker install with Docker Compose gives you SSH, VNC, RDP, Telnet, and SFTP from a single web dashboard, with proper encryption at rest, 2FA/passkey support, and session recording. It runs comfortably on a small VPS and integrates well with Traefik for HTTPS access. If you're exploring the space, check [self-hosted server management panels](https://www.bitdoze.com/best-self-hosted-panels/) for a broader comparison, or look at [alternative SSH management tools like Termix](https://www.bitdoze.com/termix-self-host/) for different trade-offs.

How to Add a Floating Menu to a Carrd Website

Tue, 04 Aug 2026 00:00:00 GMT

Home
About
Testimonials
Contact

``` Two critical fixes for returning readers: (1) The global `* { margin: 0; padding: 0; box-sizing: border-box; }` reset has been removed. It was destroying Carrd's native element spacing. (2) The `body { font-size; font-family }` override has been removed. It was hijacking all text on the page. Both are replaced with scoped selectors that only affect the floating menu itself. This code includes ARIA attributes (`aria-label`, `aria-expanded`, `role="navigation"`), visible focus outlines for keyboard users, `@media (prefers-reduced-motion: no-preference)` wrapping all animations, and Escape key support to close the menu. This addresses the European Accessibility Act (effective June 28, 2025) requirements for interactive UI elements. #### CSS custom properties explained These variables at the top of the ` ``` Carrd embeds have a 16,384 character limit. This code is roughly 1,200 characters, well within limits. **What changed from the original version:** - `prefers-reduced-motion` CSS guard prevents smooth scrolling for users with motion sensitivity - `aria-label="Back to Top"` lets screen readers identify the button - `:focus-visible` outline shows keyboard users where focus lands - Replaced `window.onscroll` with throttled `addEventListener` using `requestAnimationFrame`. Fires once per frame instead of 60+ times per second. - Replaced `document.documentElement.scrollTop = 0` with `window.scrollTo({ top: 0, behavior: 'smooth' })`. Modern, cross-browser. - `document.body.focus()` after scroll moves focus to the top for keyboard users. - Scroll threshold increased from 200px to 400px. 200px triggers almost immediately on most screens. - Removed inline `onclick`. Using `addEventListener` for cleaner separation. - Initial `toggleButton()` call on load handles pages that load mid-scroll. - Removed unnecessary `tabindex="0"`. The ` ``` And remove or comment out the `#scroll-to-top::before` CSS rule. Adjust the button `width` to `auto` and add some `padding` to fit the text. ## Accessibility & WCAG compliance for your scroll to top button The updated code above includes several accessibility fixes. Here's why they matter. ### Keyboard navigation and screen reader support The button uses a native `

How to Use Groq's FREE API in Your Streamlit App

Sat, 25 Jul 2026 00:00:00 GMT

30+ Best Python Web Frameworks for 2026 (Compared)

Fri, 24 Jul 2026 00:00:00 GMT

Rapid development: pre-built components for routing, templating, auth, and database access mean you ship faster
Built-in security: protection against CSRF, XSS, SQL injection, and other common web vulnerabilities
Scalability: most frameworks handle increased traffic through async support, caching layers, and connection pooling
Large community: popular frameworks have thousands of answered questions, production-tested patterns, and maintained extensions
Rich ecosystem: ORMs, migration tools, admin panels, API docs generators, and testing utilities that plug in cleanly

## Best Python Web Frameworks for 2026 ### Full-stack frameworks Full-stack frameworks provide a complete toolkit for server-rendered web applications: ORM, templating, authentication, admin interface, and form handling. If you want one framework to handle everything, this is the category. - **[Django](https://www.djangoproject.com/)** (5.2 LTS, 88,189 ★): The heavyweight of Python web development. Django 5.2 LTS (released April 2025) adds composite primary keys and automatic model imports in the shell. LTS support runs until April 2028. Django 6.0 (released December 2025) added template partials, built-in CSP headers, and background tasks. These features support the HTMX+Django pattern that's gaining traction for solo developers who want to avoid a separate JavaScript frontend. **[Django Repo](https://github.com/django/django)** - **[Pyramid](https://trypyramid.com)** (2.1): Pyramid's philosophy is "start small, finish big." It gives you routing and templating out of the box but lets you swap in your own database layer, auth system, and template engine. Good fit when Django feels like too much and Flask feels like too little. **[Pyramid Repo](https://github.com/Pylons/pyramid)** - **[TurboGears](https://turbogears.org)** (2.5.0): Starts as a single-file app and scales to a full-stack solution. Built on top of several other components (SQLAlchemy, ToscaWidgets, Genshi/Mako). Note: verify Python 3.10+ support before committing; check the release notes for 2.5.0. **[TurboGears Repo](https://github.com/TurboGears/tg2)** - **[Masonite](https://docs.masoniteproject.com/)** (v5): A developer-centric framework with an MVC architecture inspired by Laravel. Masonite v5 is published as `masonite-framework` on PyPI. The original Masonite 4.x repository (`MasoniteFramework/masonite`) is archived and no longer maintained. Masonite 5 is published under `masonite-framework` on PyPI. If you're starting a new project, make sure you're installing from the correct package. - **[Emmett](https://github.com/emmett-framework/emmett)**: A full-stack async framework created by the developer behind Granian (the Rust-based HTTP server). Emmett integrates tightly with Granian for deployment and supports async/await throughout its ORM and template layer. Still relatively small community-wise, but worth watching if you want a modern async alternative to Django. ### API frameworks This is the fastest-growing category and the one with the most active development. API frameworks are optimized for building REST and GraphQL APIs with automatic OpenAPI docs, Pydantic-based validation, and dependency injection. FastAPI usage hit 38% in the 2024 JetBrains survey (up from 25% in 2022), making it the #1 Python web framework by adoption. The Stack Overflow 2025 survey confirms the trend: FastAPI at 14.8% globally among all web frameworks, Flask at 14.4%. This category is where most new Python web projects start. - **[FastAPI](https://fastapi.tiangolo.com/)** (0.115.x, 100,813 ★): The framework that changed Python web development. Built on Starlette and Pydantic v2, FastAPI generates interactive API docs (Swagger + ReDoc) from your type hints. The `[standard]` extra installs Uvicorn and other essentials: ```bash pip install "fastapi[standard]" # Start dev server fastapi dev main.py # Visit http://localhost:8000/docs for auto-generated API docs ``` FastAPI's release cadence has slowed as the project matures, but it's production-stable and battle-tested. **[FastAPI Repo](https://github.com/fastapi/fastapi)** - **[Flask](https://flask.palletsprojects.com/)** (3.1.3, 71,998 ★): The original Python microframework, still going strong. Flask 3.0 dropped Python 3.7 support; 3.1 added async improvements. It's WSGI-based (not ASGI), which matters for deployment choices. Flask's extension ecosystem is massive. There's a package for nearly everything. Best when you want full control over your stack. **[Flask Repo](https://github.com/pallets/flask)** - **[Litestar](https://litestar.dev/)** (8,356 ★): The fastest-growing ASGI framework in 2025-2026. Litestar positions itself as "FastAPI with more built-in structure." It includes DTOs (data transfer objects), built-in dependency injection, GraphQL support, WebSocket handlers, and a CLI for scaffolding: ```bash pip install litestar litestar new my-app cd my-app && litestar run # Visit /schema for auto-generated OpenAPI docs ``` Litestar is not claiming to be "better" than FastAPI. It offers different trade-offs. If you want more opinionated defaults and built-in features, Litestar reduces boilerplate. If you prefer maximum flexibility and community size, FastAPI is the safer bet. **[Litestar Repo](https://github.com/litestar-org/litestar)** - **[Django Ninja](https://django-ninja.dev/)** (9,148 ★): Brings FastAPI-style ergonomics into Django. Uses Pydantic v2, Python type hints, and async support, but lives inside your existing Django project with access to Django's ORM, admin, and middleware. The best choice when you want to add a modern API to a Django app without switching frameworks. **[Django Ninja Repo](https://github.com/vitalik/django-ninja)** - **[Falcon](https://falconframework.org/)** (4.0.2, ~9,500 ★): A bare-metal Python web API framework focused on raw performance. Falcon 4.0 added ASGI support alongside its existing WSGI mode. Zero dependencies. Used by LinkedIn, OpenStack, and other high-traffic systems. Best when you need maximum throughput with minimum overhead. **[Falcon Repo](https://github.com/falconry/falcon)** - **[Sanic](https://sanic.dev/)** (25.3, ~18,000 ★): A web server and framework built for speed with async/await support. Sanic uses a `YY.M` versioning convention now. Version 25.3 was released March 2025. Requires Python 3.10+. **[Sanic Repo](https://github.com/sanic-org/sanic)** - **[Quart](https://quart.palletsprojects.com/)** (0.20.0): Maintained by the Pallets organization (the same team behind Flask), Quart is an ASGI framework with the same API as Flask. If you want async support but already know Flask's API, Quart is the migration path. Flask extensions can run on Quart with minimal changes. **[Quart Repo](https://github.com/pallets/quart)** - **[BlackSheep](https://www.neoteroi.dev/blacksheep/)** (2,351 ★): A high-performance ASGI framework inspired by Flask and ASP.NET Core. Features clean dependency injection, automatic OpenAPI docs, and excellent type hints support. Smaller community but actively maintained. **[BlackSheep Repo](https://github.com/Neoteroi/BlackSheep)** - **[Esmerald](https://esmerald.dev/)**: A modular ASGI framework designed for both APIs and full applications. Heavy focus on modularity, scalability, and pluggable architecture. Still growing in adoption, but the design is solid for complex projects that need structure. **[Esmerald Repo](https://github.com/dymmond/esmerald)** **Install:** `pip install "fastapi[standard]"` **Type system:** Pydantic v2 **DI:** Built-in (`Depends()`) **GraphQL:** Via Strawberry extension **Server:** ASGI only (Uvicorn/Granian) **Maintained by:** Sebastián Ramírez **Best for:** REST APIs, async APIs, microservices **Install:** `pip install litestar` **Type system:** Pydantic v2 + msgspec **DI:** Built-in (more structured than FastAPI) **GraphQL:** Built-in support **Server:** ASGI only (Uvicorn/Granian) **Maintained by:** Litestar Organization **Best for:** Structured APIs, larger projects needing conventions **Install:** `pip install django-ninja` **Type system:** Pydantic v2 **DI:** Django dependency system + Ninja **GraphQL:** Not built-in (use graphene-django) **Server:** WSGI or ASGI (Django's choice) **Maintained by:** Vitaliy Kucheryaviy **Best for:** Adding APIs to existing Django projects ### Asynchronous frameworks These are lower-level async networking frameworks. They're not specifically built for REST APIs (that's what the API frameworks above are for) but for building real-time applications, WebSocket servers, custom protocols, or anything that benefits from non-blocking I/O. - **[AIOHTTP](https://docs.aiohttp.org/)** (3.11.18, ~15,000 ★): Both an async HTTP client and server framework. In practice, most developers use AIOHTTP as an HTTP client (for making async requests) rather than as a web framework. The server side (`aiohttp.web`) is solid but less commonly used for new projects. **[AIOHTTP Repo](https://github.com/aio-libs/aiohttp)** - **[Starlette](https://www.starlette.io/)**: A lightweight ASGI toolkit, not a full framework. FastAPI is built on top of Starlette. You'd use Starlette directly when you want raw ASGI handling without FastAPI's opinionated layer on top. Good for custom middleware, background tasks, or WebSocket-only services. **[Starlette Repo](https://github.com/encode/starlette)** - **[Tornado](https://www.tornadoweb.org)** (6.4.2): A Python web framework and async networking library, originally developed at FriendFeed (now part of Facebook). Tornado usage has declined to 2% in the JetBrains survey, but it's still maintained and still works well for long-polling, WebSockets, and custom TCP servers. **[Tornado Repo](https://github.com/tornadoweb/tornado)** - **[Robyn](https://robyn.tech/)** (7,322 ★): A Python web framework with a Rust runtime. Robyn compiles its core server loop in Rust via PyO3, giving it near-compiled-language performance while keeping Python for your application code. Supports Python 3.13. If you need maximum throughput from a Python web server, Robyn is worth benchmarking against your workload. **[Robyn Repo](https://github.com/sparckles/Robyn)** UvLoop was previously listed in this section. It's actually an ultra-fast drop-in replacement for Python's asyncio event loop (built with Cython and libuv). It powers frameworks like Sanic under the hood, but it's infrastructure, not a web framework. Use it as a performance optimization for any asyncio-based framework: `pip install uvloop`. ### UI and data app frameworks This category barely existed when the original article was written. In 2026, "pure Python" web UI frameworks are one of the fastest-growing areas in the Python ecosystem. Reflex, Flet, NiceGUI, and Taipy collectively went from around 10,000 to over 80,000 GitHub stars in two years. These frameworks let you build complete web applications without writing JavaScript. The "pure Python UI" category has exploded: Reflex (28,667 ★), Flet (16,372 ★), NiceGUI (16,052 ★), and Taipy (19,333 ★) collectively went from ~10k stars to 80k+ in two years. Gradio alone has 43,191 stars. If you're a Python developer who doesn't want to touch JavaScript, this is the category to watch. - **[Streamlit](https://streamlit.io/)** (~36,000 ★): The standard for building data apps and ML dashboards in Python. Streamlit 1.52+ added `st.datetime_input`, dynamic tabs, and advanced theming with Google Fonts. Requires Python 3.9+. Check the [Streamlit vs Taipy](https://www.bitdoze.com/streamlit-vs-taipy/) comparison if you need more enterprise features. You can also [deploy Streamlit on a VPS](https://www.bitdoze.com/streamlit-deploy-vps-cloudflare/) for production use. **[Streamlit Repo](https://github.com/streamlit/streamlit)** - **[Gradio](https://www.gradio.app/)** (43,191 ★): The dominant framework for ML model demos and AI app interfaces. Backed by Hugging Face. Gradio 5 focused on production readiness; Gradio 6 is in development. If you're building a demo for a machine learning model or an AI application, Gradio is the default choice: it integrates directly with Hugging Face Spaces for free hosting. **[Gradio Repo](https://github.com/gradio-app/gradio)** - **[Reflex](https://reflex.dev/)** (28,667 ★): Formerly called Pynecone. Reflex compiles your Python code to a React frontend with a Next.js backend. Version 0.8.x brought 2-3x faster builds with Vite+Rolldown and 60+ built-in UI components. The `reflex deploy` command handles deployment, or you can self-host. **[Reflex Repo](https://github.com/reflex-dev/reflex)** - **[Flet](https://flet.dev/)** (16,372 ★): Build interactive multi-user web, mobile, and desktop apps in Python. Flet 1.0 Alpha (June 2025) is a major rewrite with a custom Python runtime, permissions control, and faster rebuilds. Cross-platform is Flet's differentiator: the same code runs on web, iOS, Android, Windows, macOS, and Linux. **[Flet Repo](https://github.com/flet-dev/flet)** - **[NiceGUI](https://nicegui.io/)** (16,052 ★): A user interface framework for building web applications with Python only. Version 2.x added 3D scene rendering, camera controls, and native window events. See the [Streamlit vs NiceGUI comparison](https://www.bitdoze.com/streamlit-vs-nicegui/) for when to pick each. Check the [NiceGUI beginner's guide](https://www.bitdoze.com/nicegui-get-started/) to get started. **[NiceGUI Repo](https://github.com/zauberzeug/nicegui)** - **[Taipy](https://www.taipy.io/)** (19,333 ★): Enterprise-focused data application framework. Taipy 4.x targets production data pipelines with scenario management, data node orchestration, and job scheduling. See the [Streamlit vs Taipy](https://www.bitdoze.com/streamlit-vs-taipy/) comparison for details. **[Taipy Repo](https://github.com/Avaiga/taipy)** - **[Dash (Plotly)](https://plotly.com/dash/)** (3.0.4): A framework for building data visualization apps on top of Flask, Plotly.js, and React.js. Dash 3.0 was a major release. Ideal for building analytical dashboards with highly customized interactive charts in pure Python, no JavaScript required. **[Dash Repo](https://github.com/plotly/dash)** - **[Panel](https://panel.holoviz.org/)**: A high-level dashboarding solution from the HoloViz ecosystem. Panel works with Bokeh, Matplotlib, HoloViews, and many other Python plotting libraries. Good fit when you're already in the scientific Python ecosystem. **[Panel Repo](https://github.com/holoviz/panel)** - **[ReactPy](https://reactpy.dev/)** (8,144 ★): Create interactive web applications in Python using a component model inspired by React. ReactPy lets you write JSX-like Python code that renders to the DOM. Smaller community but interesting for developers who want the React mental model without leaving Python. **[ReactPy Repo](https://github.com/reactive-python/reactpy)** - **[Anvil](https://anvil.works/)**: A platform for building full-stack web apps with nothing but Python. Client-side and server-side code are both Python. Anvil handles hosting and deployment. Note: Anvil is a commercial platform with a free tier. It's not fully open-source. **[Anvil Repo](https://github.com/anvil-works/anvil-runtime)** **Best for:** Data apps, ML dashboards, internal tools **Install:** `pip install streamlit` **Pros:** Fastest time-to-dashboard, huge community, free hosting **Cons:** Limited customization, state management quirks **Best for:** ML model demos, AI app interfaces **Install:** `pip install gradio` **Pros:** HuggingFace integration, free hosting on Spaces, API auto-generated **Cons:** Less flexible for general-purpose UIs **Best for:** Full-stack Python web apps, no JavaScript **Install:** `pip install reflex` **Pros:** 60+ components, compiles to React, full control **Cons:** Larger learning curve, newer community **Best for:** General web UIs, IoT dashboards, internal tools **Install:** `pip install nicegui` **Pros:** Simple API, 3D scenes, camera support, active dev **Cons:** Smaller ecosystem than Streamlit ### Microframeworks Minimal, near-zero-dependency frameworks for small projects, embedded use, or situations where you want full control over every component. - **[Bottle](https://bottlepy.org/)** (0.13.3): A single-file micro web framework with no dependencies outside the Python standard library. Bottle is still maintained (last release April 2025). Good for embedded systems, quick prototypes, or situations where adding dependencies is a problem. **[Bottle Repo](https://github.com/bottlepy/bottle)** - **[CherryPy](https://cherrypy.dev/)** (18.10.0): A minimalist Python web framework that lets you build web applications the same way you build any other object-oriented Python program. CherryPy includes its own production-ready, thread-pooled HTTP server. Still maintained (last release June 2024). **[CherryPy Repo](https://github.com/cherrypy/cherrypy)** ### Legacy and historical frameworks These frameworks have historical significance and some still run in production, but they're not recommended for new projects in 2026. These frameworks were important in Python's web history. Some still receive maintenance releases. But for new projects in 2026, the frameworks above offer better performance, modern Python support, active communities, and current documentation. If you're maintaining an existing app on one of these, that's fine. Just don't start new projects with them. - **[Zope](https://www.zope.dev/)** & **BlueBream**: Zope is historically important for its component architecture, which influenced many later frameworks. Zope 5.13 was released March 2025. BlueBream 1.0 was released in 2011 and is essentially frozen. If you need Zope's component model, consider modern alternatives first. **[Zope Repo](https://github.com/zopefoundation/Zope)** - **[web2py](http://www.web2py.com)**: The web2py documentation itself says: "not recommended for new projects, consider using py4web instead." JetBrain's survey shows 3% usage, flat since 2021. If you're on web2py, look at py4web as the migration path. - **[CubicWeb](https://www.cubicweb.org)** (4.10.0): Built on Semantic Web principles with an emphasis on reusability through components and explicit data models. Version 4.10.0 was released April 2025, but the community is extremely niche. Only relevant if you specifically need semantic web / linked data capabilities. - **[web.py](https://webpy.org/)**: A web framework that's as simple as it is powerful, but effectively frozen. Last release 0.62 was in November 2020. Occasional commits still land, but there's no active development. If you're using web.py for something simple, Bottle is a better maintained alternative. - **[Hug](https://hugapi.github.io/hug/)**: Last meaningful release was v2.6.1 in February 2020. The original `hug.rest` domain may no longer resolve. The project now lives on GitHub Pages. 187 open issues with no resolution. Don't use this for new projects; FastAPI covers the same use case with active maintenance. ## Django vs Flask vs FastAPI: which one should you choose? This is the most-searched comparison in the Python web space, and for good reason: Django, Flask, and FastAPI remain the three most production-proven options. The choice depends on what you're building. JetBrains 2024 survey: FastAPI 38%, Django 35%, Flask 34%. Stack Overflow 2025: FastAPI 14.8%, Flask 14.4% globally among all web frameworks. FastAPI has the momentum, but Django and Flask have the deep ecosystem and battle-tested track records. All three are production-grade. **Best for:** Full-stack web applications, admin-heavy apps, content sites, anything needing ORM + auth + admin **Python version:** 3.10+ **Key dependency:** Django ORM (built-in) **Install:** `pip install django==5.2.*` **Strengths:** Complete ecosystem, admin panel, ORM, massive community, LTS releases **Weaknesses:** Monolithic architecture, slower for pure API work, template-first mindset **Quick start:** ```bash pip install django==5.2.* django-admin startproject myproject cd myproject python manage.py runserver # Visit http://localhost:8000/ ``` **Best for:** Lightweight APIs, microservices, when you want full control over your stack **Python version:** 3.8+ **Key dependency:** Werkzeug, Jinja2 **Install:** `pip install flask` **Strengths:** Minimal, flexible, huge extension ecosystem, easy to learn **Weaknesses:** WSGI only (no native async), no built-in ORM or admin **Quick start:** ```bash pip install flask ``` ```python from flask import Flask app = Flask(__name__) @app.route("/") def hello(): return "Hello, World!" ``` ```bash flask run # Visit http://localhost:5000/ ``` **Best for:** REST/GraphQL APIs, async APIs, microservices, type-safe codebases **Python version:** 3.8+ **Key dependency:** Pydantic v2, Starlette **Install:** `pip install "fastapi[standard]"` **Strengths:** Auto OpenAPI docs, async native, type hints, fast (literally) **Weaknesses:** Younger ecosystem, no built-in ORM or admin, ASGI-only **Quick start:** ```bash pip install "fastapi[standard]" ``` ```python from fastapi import FastAPI app = FastAPI() @app.get("/") def hello(): return {"message": "Hello, World!"} ``` ```bash fastapi dev main.py # Visit http://localhost:8000/docs for auto-generated API docs ``` **Quick decision guide:** - **Need an ORM, admin panel, and user auth out of the box?** Django. - **Building a REST API with automatic docs and async support?** FastAPI. - **Want minimal overhead and full control over every component?** Flask. - **Already in Django but want FastAPI-style API ergonomics?** Django Ninja (don't switch frameworks, add it). - **Solo developer who doesn't want a JavaScript frontend?** Django + HTMX or Streamlit/NiceGUI. The HTMX + Django pattern is worth noting: Django 6.0 adds template partials specifically to support this approach. For solo operators who want to build server-rendered apps without maintaining a React/Vue frontend, Django + HTMX is a practical, low-maintenance stack. ## Deployment recommendations for Python web frameworks Once you've picked a framework, you need to deploy it. Here's the practical guide for the bitdoze audience: self-hosted on a VPS with Docker or bare metal. A $5-10/month VPS from [Hetzner Cloud](https://go.bitdoze.com/hetzner) or [DigitalOcean Droplets](https://go.bitdoze.com/do) can handle substantial traffic for most Python web applications. Managed platforms with equivalent resources typically cost $50-100+/month. If you're running a side project, startup MVP, or internal tool, self-hosting on a VPS is the cost-effective choice. Budget options like [Hostinger VPS](https://go.bitdoze.com/hostinger-vps) start even lower, and [Vultr](https://go.bitdoze.com/vultr) offers global regions if you need to deploy closer to your users. **Django:** Gunicorn (WSGI) behind Nginx or Caddy. For Docker-based deployment, use [Dokploy for self-hosting](https://www.bitdoze.com/dokploy-install/). It handles reverse proxy, SSL, and deployment from Git. Django 5.2 on a $5 VPS with 1-2 GB RAM is enough for most projects. **FastAPI:** Uvicorn or Granian (ASGI server). Granian is a Rust-based HTTP server that shows 2-4x faster throughput than Uvicorn in published benchmarks (results vary by workload). Put it behind Nginx or Caddy for SSL and static files: ```bash pip install fastapi granian granian app:app --interface asgi --port 8000 ``` **Flask:** Gunicorn (WSGI) behind a reverse proxy. Flask doesn't natively support ASGI, but Quart (maintained by the same Pallets team) gives you Flask's API with async support. **Streamlit:** Reverse proxy with Nginx + systemd service, or Docker. See the full guide on how to [deploy Streamlit on a VPS](https://www.bitdoze.com/streamlit-deploy-vps-cloudflare/). You can also [run Python apps in Docker](https://www.bitdoze.com/docker-run-python/) for isolated, reproducible deployments. **Gradio:** Free hosting on Hugging Face Spaces for demos. For production, self-host behind Nginx with systemd or Docker. **Reflex:** Built-in `reflex deploy` command for Reflex Cloud (has a free tier). Self-hosting requires the standard VPS setup. For managing your Python projects, I recommend [setting up Python projects with uv](https://www.bitdoze.com/uv-get-start/). It's significantly faster than pip and handles virtual environments cleanly. You can also [deploy Python projects with Dokploy and uv](https://www.bitdoze.com/dokploy-python-railpack-uv/) for a full CI/CD pipeline.

VPS provisioned (1-2 GB RAM minimum, 2+ GB recommended for Django/FastAPI)
Python 3.10+ installed (use uv or pyenv for version management)
Reverse proxy configured (Nginx, Caddy, or Traefik)
SSL/TLS certificates (Caddy auto-provisions, or use Certbot with Nginx)
Systemd service or Docker Compose for process management
Firewall rules (allow only 80, 443, and your SSH port)

For VPS management, check the [best self-hosted server panels](https://www.bitdoze.com/best-self-hosted-panels/) if you want a GUI for managing your deployments. ## Choosing the right Python web framework The "right" framework depends on what you're building, who's building it, and how much complexity you want to manage. Here's the decision matrix I use: **Recommendation:** FastAPI or Litestar **Why:** FastAPI is the market leader with the largest community, auto-generated docs, and Pydantic v2 validation. Litestar is the rising alternative with more built-in structure (DTOs, DI, GraphQL). Both are ASGI and perform well. **Solo operator default:** FastAPI. More tutorials, more Stack Overflow answers, more production examples. **Recommendation:** Django or Django + HTMX **Why:** Django gives you ORM, admin, auth, and templating out of the box. With HTMX, you can build interactive UIs without a separate JavaScript frontend. Django 5.2 LTS is supported until 2028. **Solo operator default:** Django + HTMX. Lowest maintenance burden for a solo developer. **Recommendation:** Gradio or Streamlit **Why:** Gradio is purpose-built for ML model demos and integrates directly with Hugging Face Spaces (free hosting). Streamlit is better for data dashboards and broader data science tools. **Solo operator default:** Gradio for ML demos, Streamlit for data dashboards. **Recommendation:** Streamlit or Dash **Why:** Streamlit is fastest to prototype with. Dash gives more control over chart customization and is built on Plotly. For internal tools, Streamlit's simplicity wins. **Solo operator default:** Streamlit. **Recommendation:** NiceGUI or Reflex **Why:** NiceGUI is simpler to start with and has a clean API. Reflex compiles to React and gives you a full-stack app with a real frontend build step. Pick NiceGUI for quick tools, Reflex for production web apps. **Solo operator default:** NiceGUI for internal tools, Reflex for user-facing apps. Start with Flask or FastAPI. Flask teaches you the fundamentals of web development (routing, templates, request/response cycle) with minimal magic. FastAPI teaches you modern Python patterns (type hints, Pydantic, async) that transfer to the rest of the ecosystem. Both have excellent official tutorials. Build a small project (a URL shortener, a todo API, a blog) and you'll learn enough to evaluate other frameworks. It depends on the switch. Going from Flask to FastAPI is relatively smooth: both are lightweight, and the routing patterns are similar. Going from Django to FastAPI is harder because Django's ORM, admin, and middleware are deeply integrated. Django Ninja gives you FastAPI-style APIs inside Django, which is often better than switching entirely. The key insight: keep your business logic separate from your framework code. If your core logic is in plain Python modules (not tied to framework decorators or ORM models), switching becomes much easier. ### Other factors to consider **Project size and scope**: Full-stack frameworks (Django) are better for larger applications. Microframeworks (Flask, Bottle) suit smaller projects. API frameworks (FastAPI, Litestar) are purpose-built for services. **Learning curve**: Django has the steepest initial learning curve but the most comprehensive documentation. Flask is the easiest to start with. FastAPI sits in between: the type hints and Pydantic model concepts take some getting used to, but the auto-generated docs pay off immediately. **Community and support**: Django (88k stars), FastAPI (101k stars), and Flask (72k stars) have the largest communities. Smaller frameworks like Litestar and NiceGUI are growing fast but have fewer answered questions available. **Long-term viability**: Django has been around since 2005 and has LTS releases with 3+ years of support. FastAPI and Flask are both actively maintained with strong funding and community backing. Newer frameworks carry more risk. Evaluate the maintainer's track record and funding model. **Performance**: For raw API throughput, ASGI frameworks (FastAPI, Litestar, Sanic, Robyn) outperform WSGI frameworks (Flask, Django) under concurrent load. But for most applications, the framework choice matters less than your database queries and caching strategy. ## Conclusion Python web development in 2026 is more diverse than ever. FastAPI has overtaken Django and Flask in adoption, but all three remain production-grade choices for different kinds of projects. The "pure Python" UI explosion (Gradio, Streamlit, Reflex, NiceGUI) means Python developers can build full web applications without writing JavaScript. Rust-powered tooling (Robyn, Granian, uv) is pushing the performance ceiling higher. The best framework is the one that fits your project, your team, and your deployment constraints. If you're a solo operator on a VPS, FastAPI or Flask give you the least friction. If you need an admin panel and ORM, Django is still the answer. If you're building an AI demo, Gradio is the default. Pick one, build something this weekend, and deploy it.

Build Your Own AI Agent with Mastra (Files, Web, Browser)

Fri, 24 Jul 2026 00:00:00 GMT

Bunny.net Review 2026: Honest Take After 1 Year (Cheaper Than Cloudflare)

Fri, 24 Jul 2026 00:00:00 GMT

import Button from "@components/widgets/Button.astro"; import Notice from "@components/widgets/Notice.astro"; import ListCheck from "@components/widgets/ListCheck.astro"; import Accordion from "@components/widgets/Accordion.astro"; import Tabs from "@components/widgets/Tabs.astro"; import Tab from "@components/widgets/Tab.astro"; import YouTubeEmbed from "@components/widgets/YouTubeEmbed.astro"; I have been running sites on [Bunny.net](https://go.bitdoze.com/bunny) for over a year: CDN in front of WordPress, plus their Stream product for video. Before that I was on Cloudflare free and briefly on CloudFront. CloudFront's pricing made me grumpy (bandwidth *and* per-request fees?), and Cloudflare free is hard to beat on price, but I wanted real cache control and video without duct-taping three vendors together. Bunny fixed most of that. Not all of it. After twelve months in production, here is what still holds up and what still bugs me. You can test everything in this review yourself. [Sign up at Bunny.net](https://go.bitdoze.com/bunny) with no credit card required and get a full 14-day free trial. ## What Bunny.net actually is Bunny.net started life as a CDN (they used to be called BunnyCDN) but has since grown into a full edge platform. Think of it as a smaller, cheaper alternative to the AWS stack of CloudFront + S3 + MediaConvert, except everything lives under one dashboard and the pricing doesn't require a spreadsheet to decode. ![Bunny.net main dashboard interface](../../assets/images/26/04/bunny-main-interface.webp) The company is based in Slovenia, which means they fall under EU data protection laws. They run 119+ edge locations across 82 countries, with a network capacity over 250 Tbps. Here's everything they offer right now: | Service | What it does | Starting price | |---------|-------------|----------------| | **Bunny CDN** | Content delivery network | $0.01/GB (EU/NA) | | **Bunny Stream** | Video hosting and streaming | $0.01/GB storage + delivery | | **Bunny Storage** | Edge-replicated object storage | $0.01/GB (single region) | | **Bunny Optimizer** | Image/CSS/JS optimization | $9.50/mo per site | | **Bunny DNS** | Scriptable DNS with monitoring | Free (included) | | **Bunny Shield** | WAF, DDoS, bot protection | Free tier available | | **Bunny Database** | SQLite-compatible global database | $0.30/billion reads | | **Edge Scripting** | Serverless functions (Deno) | $0.20/million requests | | **Magic Containers** | Global Docker deployment | Pay per CPU/memory usage | That's a lot of products for a company that started as "just a CDN." Let me go through the ones that matter most. ## Bunny CDN: the core product This is what most people sign up for, and it's still the strongest part of the platform. ![Bunny CDN pull zone interface](../../assets/images/26/04/bunny-cdn-interface.webp) ### How it works You create a "pull zone" that sits in front of your origin server. Bunny caches your content across their 119 PoPs and serves it from whichever location is closest to your visitor. Setup takes about 5 minutes: point your pull zone at your origin, update your DNS, and you're running. ### My experience with WordPress I've been using Bunny CDN with my WordPress sites and the setup was painless. They have a WordPress plugin that configures everything automatically, but even without it, you just swap your asset URLs to the Bunny pull zone hostname and you're done. What I noticed right away was the drop in origin server load. With Perma-Cache enabled, my VPS went from handling every single request to barely seeing any traffic at all. Page load times improved across the board, especially for visitors outside Europe where my server sits. The TTFB (Time to First Byte) for cached assets dropped to under 30ms for most locations. If you're running WordPress on a budget VPS (Hetzner, DigitalOcean, etc.), adding Bunny CDN in front of it is probably the single best performance upgrade you can make for the money. ### Performance Bunny claims 24ms average global latency, and from my testing, that checks out for EU and NA traffic. Asia-Pacific varies more, somewhere between 30-60ms depending on the specific country. For context, Cloudflare typically hits 15-20ms (they have more PoPs), but Bunny is faster than CloudFront in most regions outside the US. The real performance win is their Perma-Cache feature. Regular CDN caching expires and needs to re-fetch from your origin. Perma-Cache stores your content on edge storage permanently, so you get a near-100% cache hit ratio. Your origin server barely gets touched. ### Key features - **Perma-Cache**: Permanent edge storage for near-100% cache hit ratio - **SmartEdge routing**: Sends users to the fastest PoP, not just the nearest one - **Edge Rules**: Custom logic for redirects, headers, caching, and security - **Real-time analytics**: Traffic monitoring with raw log access - **Instant purge**: Cache clearing propagates in seconds - **Free SSL**: Let's Encrypt certificates with one click - **DDoS protection**: Built into every plan, no extra charge - **SafeHop**: Configurable origin timeouts and automatic retry logic ### CDN pricing Bunny runs two network tiers: Region-based pricing with full global coverage: | Region | Price per GB | |--------|-------------| | Europe & North America | $0.01 | | Asia & Oceania | $0.03 | | South America | $0.045 | | Middle East & Africa | $0.06 | Good for: Most websites, apps, and projects that need worldwide reach. Single flat rate for high-bandwidth projects: | Tier | Price per GB | |------|-------------| | First 500 TB | $0.005 | | 500 TB - 1 PB | $0.004 | | 1 PB - 2 PB | $0.002 | | 2 PB+ | Contact them | Good for: Video platforms, large file distribution, anything bandwidth-heavy. To put this in perspective: 5 TB of EU/NA traffic on Bunny costs about $50. The same on CloudFront runs $425+. On Fastly, over $600. That's not a typo. ## Bunny Stream: video without the headaches ![Bunny Stream video library interface](../../assets/images/26/04/bunny-stream-interface.webp) This is the other service I use regularly, and it's the main reason I'm not on Vimeo or Wistia anymore. I wrote a full [step-by-step guide to setting up Bunny Stream](/bunny-stream-guide/) if you want the hands-on walkthrough. Here's the overview. ### What you get Upload a video, Bunny transcodes it into multiple resolutions (240p through 1080p, with 4K available), replicates it across their storage regions, and serves it through the CDN with an embedded player. The player is customizable (colors, controls, language) or you can pull the raw HLS stream URLs and use your own player. ### Why I moved away from Vimeo Cost. Vimeo's pricing for video hosting adds up fast once you have more than a handful of videos. Bunny Stream charges for storage ($0.01/GB) and delivery bandwidth. Transcoding is free. The player is free. DRM is included if you need it. For 300 GB of stored video with 50 GB of monthly traffic and a single replication point, you're looking at roughly $3.50/month. Try getting that number from any traditional video platform. ### Stream features - **Free transcoding**: No per-minute encoding costs - **Adaptive bitrate**: HLS streaming across multiple quality levels - **Custom player**: Full control over colors, controls, watermarks, language - **DRM protection**: Enterprise-grade, blocks downloads and screen recording - **Token authentication**: Control exactly who can watch your videos - **Hotlink protection**: Block unauthorized embedding on other sites - **TUS resumable uploads**: Large uploads that survive connection drops - **API-first design**: Full REST API with webhook support - **AI content tagging**: Automatic categorization of video content ### Stream vs traditional cloud providers | Feature | Bunny Stream | Traditional (AWS etc.) | |---------|-------------|----------------------| | Encoding | Free | ~$0.02/minute | | Storage | $0.01/GB | ~$0.02/GB | | CDN delivery | From $0.005/GB | From $0.085/GB | | Player | Included free | Requires external integration | | DRM | Included | Extra charges | | Setup complexity | Minutes | Hours to days | ## Other Bunny.net services I don't use all of these daily, but here's what each one does and who it's meant for. ![Bunny Storage file manager interface](../../assets/images/26/04/bunny-storage-interface.webp) Edge-replicated object storage across up to 15 regions. Think S3, but your files get automatically copied to multiple locations worldwide. **Pricing:** | Setup | Price per GB | |-------|-------------| | Single region | $0.01 | | Two regions | $0.02 | | Three regions | $0.025 | | Each additional | +$0.005 | No egress fees when delivering through Bunny CDN, no API request charges, and automatic global replication. Bunny reports 41ms average global latency compared to 131ms for AWS S3 in EU Central. The distributed architecture makes that number plausible. Upload via FTP, SFTP, HTTP API, or their web file manager. I put together a detailed [Bunny Storage vs S3 vs Backblaze B2 comparison](/bunny-storage-vs-s3-vs-backblaze/) if you want to see how the pricing stacks up against other providers. With their new S3-compatible API, you can also [mount a Bunny bucket as a filesystem on a VPS](/s3-bucket-filesystem-vps/) using ZeroFS or JuiceFS. Automatic image optimization, WebP/AVIF conversion, and CSS/JS minification. Connect your site and it handles everything on the fly without plugins or code changes. **Pricing:** $9.50/month per website. Flat rate, unlimited requests and optimizations. **What it does:** - Compresses images by up to 80% - Converts to WebP based on browser support - Resizes images per device type - Minifies CSS and JavaScript If you're already running image optimization through your build process (like I do with Astro), this may be redundant. But for WordPress sites or anything serving unoptimized images, the Core Web Vitals improvement is noticeable. Free DNS hosting with some extras you don't see elsewhere: scriptable DNS records (write actual routing logic in code), built-in health monitoring for A records, load balancing, and geographic routing. Runs on 36+ anycast PoPs with sub-20ms latency in most regions. If you're already on Cloudflare DNS, there's no strong reason to migrate unless you need the scripting capability. But if you're using Bunny CDN anyway, having DNS in the same dashboard simplifies things. Their security product, launched fairly recently. Combines a WAF, DDoS mitigation, bot detection, rate limiting, and upload scanning under one roof. **Pricing tiers:** | Feature | Basic (Free) | Advanced ($9.50/mo) | Business ($99/mo) | |---------|-------------|--------------------|--------------------| | WAF rules | 71 built-in | 255 built-in | 255 built-in | | Custom WAF rules | No | 10 | 25 | | DDoS protection | Yes | Yes | Yes | | Bot mitigation | Basic | Advanced | Advanced | | Rate limiting | No | Yes | Yes | The free tier covers basic WAF rules and DDoS protection, which is already more than many CDNs include by default. Paid tiers add custom rules, smarter bot detection, and rate limiting per IP or path. Serverless functions running on Deno, deployed across all 119 edge locations. Write TypeScript or JavaScript, push to GitHub, and it goes live globally in under 100ms. **Pricing:** $0.20 per million requests + $0.02 per 1,000 seconds of CPU time. This competes with Cloudflare Workers and Deno Deploy. The Deno runtime gives you TypeScript support out of the box, and since Deno is open source, you avoid vendor lock-in. Useful for: A/B testing, auth middleware, API gateways, request routing, or any situation where compute needs to live close to the user. A SQLite-compatible database service that runs on Bunny's global network. You create a database, pick a primary region, and optionally add read replicas in any of their 41 available regions. When nobody's querying it, the database spins down and you only pay for storage. It uses the libSQL protocol, so you connect with official SDKs for TypeScript/JavaScript, Go, Rust, and .NET. There's also a plain HTTP API if your stack doesn't have an SDK yet. **Pricing (pay-as-you-go):** | Resource | Cost | |----------|------| | Reads | $0.30 per billion rows | | Writes | $0.30 per million rows | | Storage | $0.10 per GB per active region/month | Currently in public preview and free to use while it lasts. **Best suited for:** Product catalogs, user profiles, app configuration, metadata filtering, and other read-heavy workloads. Since it's built on SQLite, it's not the right pick for write-heavy transactional systems, but for most web applications the read/write ratio makes it a good fit. Pairs well with Edge Scripting or Magic Containers for a full edge-native stack. I put together a hands-on walkthrough on [building a todo app with TanStack Start, Bunny Database, and Drizzle ORM](/tanstack-start-bunny-database-drizzle/), and another on [using Astro DB with Bunny Database](/astro-db-bunny-database/), if you want to see it wired into a real app. Their newest and most ambitious product. Deploy Docker containers across 40+ global locations with AI-powered auto-scaling. No Kubernetes setup, no DevOps overhead. Each container runs fully isolated (not crammed into shared processes like some serverless platforms), with NVMe storage and high-frequency CPUs. Their pitch is 5x cost savings over traditional edge hosting, because AI only provisions resources where and when traffic actually demands them. **Use cases:** API services, game servers, DNS clusters, real-time apps, image processing, microservices. Still fairly new, so it's less battle-tested than something like AWS ECS or Fly.io. But the concept is solid, especially if you're currently babysitting Docker deployments on VPS instances. ## The dashboard and developer experience One thing I keep coming back to is how clean the dashboard is. After spending time in the AWS Console (which feels like it was designed to confuse people) and Cloudflare's increasingly cluttered interface, Bunny's dashboard feels straightforward. Everything is where you'd expect it. Pull zone settings, analytics, storage management, video libraries. The real-time analytics actually update in real time, and the raw log explorer is genuinely useful when you're debugging cache misses or weird routing behavior. The API is well-documented and consistent across services. If you're automating deployments or building integrations, you won't spend hours fighting undocumented edge cases. ## What I like - **Pricing transparency**: No hidden fees, no per-request charges, no surprise bills - **$1 monthly minimum**: Small projects cost basically nothing to run - **14-day free trial**: No credit card needed to start - **Perma-Cache**: Near-100% cache hit ratio without complicated configuration - **All-in-one platform**: CDN, storage, video, database, DNS, and security in one place - **Support quality**: 5-minute average first response, 3-hour average resolution, 24/7 - **Pay-as-you-go**: Scale down to zero when you don't need it - **EU-based company**: GDPR compliance built in, data stays where you want it - **Overcharge protection**: Set monthly bandwidth limits to avoid bill surprises ## What bugs me - **Smaller network than Cloudflare**: 119 PoPs vs 300+, noticeable in some Asian regions - **No free CDN tier**: Cloudflare's free plan is tough to compete with for hobby projects - **Optimizer per-site pricing**: $9.50/month per site adds up when you manage multiple properties - **Magic Containers still maturing**: Less proven than AWS ECS or Fly.io for production workloads - **No built-in web analytics**: You'll still need a separate analytics tool - **Shield UI needs polish**: The WAF rule editor feels basic next to Cloudflare's ## Bunny.net vs the competition Here's how Bunny compares against the CDNs you're likely considering: | Feature | Bunny.net | Cloudflare | CloudFront | Fastly | |---------|-----------|-----------|------------|--------| | CDN pricing (EU/NA) | $0.01/GB | Free tier / $0.05/GB | $0.085/GB | $0.12/GB | | 5 TB cost (EU/NA) | ~$50 | Free* / ~$250 | $425+ | $600+ | | Global PoPs | 119 | 300+ | 450+ | 72 | | Avg. global latency | 24ms | ~15ms | ~27ms | ~29ms | | Video streaming | Built-in | No | Separate service | No | | Object storage | Built-in | R2 | S3 (separate billing) | No | | Database | Built-in (SQLite) | D1 | DynamoDB (separate) | No | | Free SSL | Yes | Yes | Yes | Yes | | DDoS protection | Included | Included | AWS Shield | Included | | Free tier | 14-day trial | Yes (generous) | 12-month trial | No | | Min. monthly cost | $1 | $0 | ~$1 | $50 | Cloudflare's free tier is unbeatable if all you need is basic CDN caching. But once you start adding storage, video hosting, and compute, the cost comparison shifts fast. Bunny's advantage is having everything bundled at straightforward per-GB rates. Performance numbers come from CDNPerf independent testing (March 2025). Pricing is from each provider's public pricing page. Your actual results will depend on your visitors' locations and origin server setup. ## Who should use Bunny.net **Good fit for:** - Small to medium sites that need CDN features beyond Cloudflare's free tier - Anyone hosting video content (courses, tutorials, marketing videos) who wants off Vimeo or Wistia pricing - Developers who want CDN + storage + compute in one dashboard - WordPress sites looking for easy CDN integration and image optimization - Businesses in the EU that care about data sovereignty **Probably not the best fit for:** - Hobby projects with zero budget (Cloudflare's free plan covers that) - Large enterprises with complex multi-cloud architectures (the AWS ecosystem goes deeper) - Sites that need 300+ PoPs for minimum latency in every corner of the world ## Frequently asked questions From personal experience, yes. I've been running Bunny CDN with WordPress and the difference in load times was obvious from day one. They have a WordPress plugin that handles CDN integration automatically, and combined with Bunny Optimizer ($9.50/mo) for image compression and JS/CSS minification, it's one of the simpler CDN setups for WordPress. You can also pair it with Varnish and Redis on your server for a full caching stack. The whole setup took me about 10 minutes. Cloudflare has a better free tier and more edge locations. Bunny has cheaper paid bandwidth, built-in video streaming, and simpler pricing once you're past the free tier. If Cloudflare's free plan already does what you need, there's no urgent reason to switch. If you need video hosting or predictable bandwidth pricing at scale, Bunny makes more financial sense. For most course creators, yes. You get adaptive bitrate streaming, DRM protection (blocks downloads and screen recording), token authentication, and a customizable player. The main thing you lose compared to Vimeo is their built-in course platform integrations, but if you're running your own LMS, Bunny's API handles embedding without issues. Credit cards (Visa, Mastercard, American Express), PayPal, and cryptocurrency. The $1 monthly minimum means you can run small projects without committing to much. Yes, and it works well. You can deploy your static site to Bunny Storage and serve it through Bunny CDN for a fully edge-hosted setup. I run my Astro site this way. Perma-Cache plus edge storage means your site loads from the nearest PoP every time, no origin server needed. 14 days, no credit card required, full access to all features. After the trial, the $1 monthly minimum kicks in, which honestly covers most small projects without any noticeable cost. ## My take after using it in production Bunny.net sits in a spot that most CDN providers miss. It's cheaper than the big cloud providers by a wide margin, more capable than most budget CDNs, and the combined platform (CDN + storage + video + database + DNS + security) means you're not duct-taping five separate services together. The video streaming alone saved me a meaningful amount compared to what I was paying for Vimeo. CDN performance lands within reach of providers charging 5-10x more. And the support team actually responds in minutes, which still catches me off guard after years of waiting 48 hours for AWS to acknowledge a ticket. It's not flawless. The network is smaller than Cloudflare's, the security dashboard could use more work, and the newer products like Magic Containers and Edge Scripting are still finding their legs. But for the price, I haven't found a better combination of features and performance. If you're currently overpaying for CloudFront, want video hosting without Vimeo's pricing, or just need a CDN that doesn't require an AWS certification to set up, Bunny.net is worth trying.

Clone Your Voice with Fish Audio in 2 Minutes (2026 Guide)

Fri, 24 Jul 2026 00:00:00 GMT

Fish Audio Review 2026: Free AI Voice Cloning That Sounds Human

Fri, 24 Jul 2026 00:00:00 GMT

Fish Audio vs ElevenLabs 2026: I Switched and Saved $84/Year

Fri, 24 Jul 2026 00:00:00 GMT

Fish Audio vs MiniMax 2026: Which AI Voice Tool Wins?

Fri, 24 Jul 2026 00:00:00 GMT

Voice quality and naturalness comparison
Voice cloning speed and fidelity
Emotion and expression controls
Language support and multilingual performance
Developer API and pricing
Which platform fits different use cases

## The short version Fish Audio wins on library size, developer pricing, free API tier, and language coverage (83 languages). MiniMax sounds great, especially in Chinese, and its sound tags for laughs and breaths are fun for expressive narration. If you are multilingual or cost-sensitive, start with Fish. If Chinese quality is the whole job, try MiniMax first. | Feature | Fish Audio | MiniMax | |---------|-----------|---------| | Latest model | S2.1 Pro | Speech 2.8 (HD/Turbo) | | Languages | 83 | 40+ | | Voice cloning audio needed | 10-15 seconds | 10 seconds | | Community voices | 2 million+ | 300+ | | Emotion control | Tags like (excited), (whisper) | Tags + sound effects (laughs), (breath) | | API pricing | $15/million chars | $60-100/million chars | | Free tier | Yes, with free S2.1 Pro API | Limited free usage | | Best for | Multilingual, budget-conscious | Chinese content, expressive narration |

How to Install WordPress with Docker Compose: Full Stack Guide

Fri, 24 Jul 2026 00:00:00 GMT

import { Picture } from "astro:assets"; import imag1 from "../../assets/images/24/01/cloudflare-tunel-setup.png"; import imag2 from "../../assets/images/24/02/docker-wp-access.png"; import YouTubeEmbed from "../../components/widgets/YouTubeEmbed.astro"; import Button from "@components/widgets/Button.astro"; import Notice from "@components/widgets/Notice.astro"; import ListCheck from "@components/widgets/ListCheck.astro"; import Accordion from "@components/widgets/Accordion.astro"; import Tabs from "@components/widgets/Tabs.astro"; import Tab from "@components/widgets/Tab.astro"; This guide walks you through installing WordPress with Docker Compose, covering a complete production-ready stack: MySQL 8.4 LTS, phpMyAdmin, automated database backups, optional Redis object caching, and Cloudflare Tunnels for SSL. Everything runs in five containers managed by a single `compose.yaml` file on any Linux VPS or [Mini PC home server](https://www.bitdoze.com/best-mini-pc-home-server/). You'll need a Linux VPS. I recommend [Hetzner](https://go.bitdoze.com/hetzner) for the best price-to-performance ratio in Europe, or [Hostinger](https://go.bitdoze.com/hostinger-vps) if you prefer NVMe storage at a budget price. If you are running WooCommerce, you can also deploy the [Woo Admin product dashboard](https://www.bitdoze.com/woocommerce-admin-dashboard/) alongside WordPress in Docker for faster product management. Here's what you get by following this guide:

WordPress container (pinned PHP version, persistent volume)
MySQL 8.4 LTS database (supported until 2032)
phpMyAdmin for database management
Automated database backups with rotation
Redis object cache for faster database queries
SSL via Cloudflare Tunnels (free plan)

> I'll use `latest` for some image tags below, but you can pin exact versions if you prefer predictable deploys. The one exception is MySQL. More on that in Step 3. ## WordPress Docker Compose Stack: Step-by-Step Setup ### 1. Prerequisites for your WordPress Docker stack

A Linux VPS with 2GB+ RAM (4GB recommended for WordPress + Redis + phpMyAdmin)
Docker Engine 24+ and Docker Compose V2 (the docker compose plugin, not standalone docker-compose)
A domain name pointed at your server (or use direct IP access)
A Cloudflare account (free plan) for Tunnels and SSL
Port 5010 and 5011 available (or pick your own)

This guide uses Docker Compose V2 syntax. The standalone `docker-compose` (V1) is deprecated and no longer receives updates. All examples use `compose.yaml` naming. If you're still on V1, upgrade with `apt install docker-compose-plugin` or check your distro's docs. Dockge is optional but recommended. It gives you a web UI to manage your compose stacks without SSH-ing into the server. Check [Dockge Install - Docker Compose Manager for Self-Hosting](https://www.bitdoze.com/dockge-install/) for the full setup. If you prefer a home server over a VPS, have a look at the [best Mini PCs for home server](https://www.bitdoze.com/best-mini-pc-home-server/). An [ASUS DC510](https://go.bitdoze.com/asus-dc510) works well for this kind of stack. Familiarize yourself with these [essential Docker commands](https://www.bitdoze.com/docker-commands/) before moving on. They'll help with troubleshooting. ### 2. Create the project directory and config files Docker bind-mounts behave badly when the source file doesn't exist. Docker creates a directory instead of a file, and your PHP config won't load. Create the config files first: ```sh # Navigate to where the stack will live cd /opt/stacks/wordpress # Create the config directory and empty files mkdir -p config touch ./config/wp_php.ini touch ./config/pma_php.ini touch ./config/pma_config.php # Set ownership so containers can write to volumes # WordPress runs as UID 1000 inside the container chown -R 1000:1000 ./config ``` If you skip creating these files first, Docker will create them as directories, and your PHP config won't load. After the first `docker compose up`, also check ownership of the data directories: `chown -R 1000:1000 ./wp-app ./db_data ./backups` to avoid permission denied errors inside WordPress. Verify the files were created correctly: ```sh ls -la ./config/ ``` You should see regular files (`-rw-r--r--`), not directories (`drwxr-xr-x`). ### 3. Docker Compose file: WordPress, MySQL 8.4 LTS and phpMyAdmin Here's the full `compose.yaml` with all five services. I'll explain the key decisions after the code. ```yaml services: wp: image: wordpress:php8.3 restart: unless-stopped ports: - 5010:80 volumes: - ./config/wp_php.ini:/usr/local/etc/php/conf.d/conf.ini - ./wp-app:/var/www/html environment: WORDPRESS_DB_HOST: wp-db:3306 WORDPRESS_DB_NAME: "${DB_NAME}" WORDPRESS_DB_USER: "${DB_USER}" WORDPRESS_DB_PASSWORD: "${DB_PASSWORD}" WORDPRESS_TABLE_PREFIX: "wp_" WORDPRESS_CONFIG_EXTRA: | define('FS_METHOD', 'direct'); depends_on: wp-db: condition: service_healthy healthcheck: test: ["CMD", "curl", "-f", "http://localhost/wp-admin/install.php"] interval: 30s timeout: 10s retries: 3 deploy: resources: limits: memory: 512M reservations: memory: 256M wp-db: image: mysql:8.4 volumes: - ./db_data:/var/lib/mysql restart: unless-stopped environment: MYSQL_ROOT_PASSWORD: "${DB_ROOT_PASSWORD}" MYSQL_DATABASE: "${DB_NAME}" MYSQL_USER: "${DB_USER}" MYSQL_PASSWORD: "${DB_PASSWORD}" healthcheck: test: ["CMD", "mysqladmin", "ping", "-h", "localhost"] interval: 10s timeout: 5s retries: 5 deploy: resources: limits: memory: 1G reservations: memory: 512M pma: image: phpmyadmin:latest ports: - 5011:80 volumes: - ./config/pma_php.ini:/usr/local/etc/php/conf.d/conf.ini - ./config/pma_config.php:/etc/phpmyadmin/config.user.inc.php restart: unless-stopped environment: PMA_HOST: wp-db PMA_PORT: 3306 MYSQL_ROOT_PASSWORD: "${DB_ROOT_PASSWORD}" UPLOAD_LIMIT: 100M depends_on: - wp-db wp-db-backup: image: tiredofit/db-backup:4.1 volumes: - ./backups:/backup restart: unless-stopped environment: DB_TYPE: mysql DB_HOST: wp-db DB_NAME: "${DB_NAME}" DB_USER: "${DB_USER}" DB_PASS: "${DB_PASSWORD}" DB_BACKUP_INTERVAL: 720 DB_CLEANUP_TIME: 72000 CHECKSUM: SHA1 COMPRESSION: ZSTD CONTAINER_ENABLE_MONITORING: "false" depends_on: - wp-db ``` ```yaml services: wp: build: context: . dockerfile: Dockerfile restart: unless-stopped ports: - 5010:80 volumes: - ./config/wp_php.ini:/usr/local/etc/php/conf.d/conf.ini - ./wp-app:/var/www/html environment: WORDPRESS_DB_HOST: wp-db:3306 WORDPRESS_DB_NAME: "${DB_NAME}" WORDPRESS_DB_USER: "${DB_USER}" WORDPRESS_DB_PASSWORD: "${DB_PASSWORD}" WORDPRESS_TABLE_PREFIX: "wp_" WORDPRESS_CONFIG_EXTRA: | define('FS_METHOD', 'direct'); define('WP_REDIS_HOST', 'redis-wp'); define('WP_REDIS_PORT', 6379); define('WP_REDIS_DATABASE', 0); depends_on: wp-db: condition: service_healthy redis-wp: condition: service_started healthcheck: test: ["CMD", "curl", "-f", "http://localhost/wp-admin/install.php"] interval: 30s timeout: 10s retries: 3 deploy: resources: limits: memory: 512M reservations: memory: 256M wp-db: image: mysql:8.4 volumes: - ./db_data:/var/lib/mysql restart: unless-stopped environment: MYSQL_ROOT_PASSWORD: "${DB_ROOT_PASSWORD}" MYSQL_DATABASE: "${DB_NAME}" MYSQL_USER: "${DB_USER}" MYSQL_PASSWORD: "${DB_PASSWORD}" healthcheck: test: ["CMD", "mysqladmin", "ping", "-h", "localhost"] interval: 10s timeout: 5s retries: 5 deploy: resources: limits: memory: 1G reservations: memory: 512M pma: image: phpmyadmin:latest ports: - 5011:80 volumes: - ./config/pma_php.ini:/usr/local/etc/php/conf.d/conf.ini - ./config/pma_config.php:/etc/phpmyadmin/config.user.inc.php restart: unless-stopped environment: PMA_HOST: wp-db PMA_PORT: 3306 MYSQL_ROOT_PASSWORD: "${DB_ROOT_PASSWORD}" UPLOAD_LIMIT: 100M depends_on: - wp-db wp-db-backup: image: tiredofit/db-backup:4.1 volumes: - ./backups:/backup restart: unless-stopped environment: DB_TYPE: mysql DB_HOST: wp-db DB_NAME: "${DB_NAME}" DB_USER: "${DB_USER}" DB_PASS: "${DB_PASSWORD}" DB_BACKUP_INTERVAL: 720 DB_CLEANUP_TIME: 72000 CHECKSUM: SHA1 COMPRESSION: ZSTD CONTAINER_ENABLE_MONITORING: "false" depends_on: - wp-db redis-wp: image: redis:7-alpine restart: unless-stopped volumes: - ./redis_data:/data deploy: resources: limits: memory: 256M reservations: memory: 128M ``` `mysql:latest` now tracks MySQL 9.x Innovation releases, short-lived versions with only ~3 months of support per minor release. For WordPress in production, use `mysql:8.4` (LTS, supported until April 2032). The `mysql:lts` tag also works as a moving LTS pointer. Since July 2024, MySQL uses a dual release track. **Innovation** releases (9.x) ship new features quarterly but have a short support window. Fine for testing, bad for production. **LTS** releases (8.4, future 9.7) get 5 years of premier support plus 3 years of extended support. Always use LTS for anything that stores data you care about. Key decisions in this compose file: - **`wordpress:php8.3`** instead of `wordpress:latest`: pins PHP to 8.3, which is the WordPress-recommended version. The `latest` tag also ships PHP 8.3 as of mid-2025, but pinning the tag avoids surprises when the default changes. - **`mysql:8.4`**: the current LTS release, supported until 2032. - **`redis:7-alpine`**: pinned version, Alpine-based for a smaller image (~30MB vs ~130MB). - **`tiredofit/db-backup:4.1`**: pinned major version. This image is migrating to `nfrastack/container-db-backup`. The old one still works fine but watch for the new release. - **`COMPRESSION: ZSTD`**: the new default in db-backup, faster compression and decompression than GZ. - **`FS_METHOD: direct`**: tells WordPress to write files directly instead of using FTP, which doesn't work in Docker. - **Health checks**: MySQL has a `mysqladmin ping` check, WordPress has a `curl` check. The `depends_on: condition: service_healthy` means WordPress waits for MySQL to be actually ready, not just started. - **Resource limits**: keeps each container from eating all your RAM. Adjust based on your VPS size. For production, consider [Docker Compose secrets](https://www.bitdoze.com/docker-compose-secrets/) instead of `.env` files. They're more secure and don't leave credentials in shell history or process listings. ### 4. Configure the .env file and security keys Create a `.env` file in the same directory as your `compose.yaml`: ```sh DB_NAME='wordpress' DB_USER='wp' DB_PASSWORD='use-a-strong-random-password-here' DB_ROOT_PASSWORD=another-strong-random-password ``` Now add the WordPress security salts. These are 8 cryptographic keys that WordPress uses to encrypt cookies and authentication tokens. The official Docker image generates unique random SHA1 hashes from whatever values you provide. It's a free security upgrade. Adding WordPress security salts costs nothing and makes session hijacking significantly harder. The Docker image reads these environment variables and writes the corresponding `define()` constants into `wp-config.php` on first boot. Add these to your `.env` file: ```sh WORDPRESS_AUTH_KEY='put-unique-phrase-here' WORDPRESS_SECURE_AUTH_KEY='put-unique-phrase-here' WORDPRESS_LOGGED_IN_KEY='put-unique-phrase-here' WORDPRESS_NONCE_KEY='put-unique-phrase-here' WORDPRESS_AUTH_SALT='put-unique-phrase-here' WORDPRESS_SECURE_AUTH_SALT='put-unique-phrase-here' WORDPRESS_LOGGED_IN_SALT='put-unique-phrase-here' WORDPRESS_NONCE_SALT='put-unique-phrase-here' ``` Generate real random values from the official WordPress salt generator:

Zcode Review 2026: Free AI Coding Agent With Goal Mode (vs Cursor)

Fri, 24 Jul 2026 00:00:00 GMT

import { Image } from "astro:assets"; import Button from "@components/widgets/Button.astro"; import Notice from "@components/widgets/Notice.astro"; import ListCheck from "@components/widgets/ListCheck.astro"; import Accordion from "@components/widgets/Accordion.astro"; import Tabs from "@components/widgets/Tabs.astro"; import Tab from "@components/widgets/Tab.astro"; import YouTubeEmbed from "@components/widgets/YouTubeEmbed.astro"; import zcodeInterface from "../../assets/images/26/02/zcode-interface.webp"; import zcodeModelsPanel from "../../assets/images/26/02/zcode-apikey-models-panel-en.webp"; import zcodePermissions from "../../assets/images/26/02/zcode-agent-permissions-en.webp"; import zcodeAgentsCall from "../../assets/images/26/02/zcode-agents-call-en.webp"; import zcodeSkillList from "../../assets/images/26/02/zcode-skill-list-en.webp"; import zcodeMcp from "../../assets/images/26/02/zcode-mcp.webp"; import zcodePluginDiscover from "../../assets/images/26/02/zcode-plugin-discover-en.webp"; import zcodeWelcome from "../../assets/images/26/07/zcode-welcome-workspace.webp"; import zcodeAgentFramework from "../../assets/images/26/07/zcode-agent-framework.png"; import zcodeExecutionModes from "../../assets/images/26/07/zcode-execution-modes.png"; import zcodeGoalMode from "../../assets/images/26/07/zcode-goal-mode.png"; import zcodeRemoteControl from "../../assets/images/26/07/zcode-remote-control.png"; import zcodeBotChannel from "../../assets/images/26/07/zcode-bot-channel.png"; I wanted a free desktop coding agent that could chew through long tasks without me babysitting it. That is basically Zcode: download it, hook up a model, and let Goal Mode keep going until the job is done. Bot Channels put the same session on your phone. Multi-model is supported if you do not want to live on GLM alone. Zcode is the official desktop app from [Z.AI](https://go.bitdoze.com/glm), the folks behind GLM. File manager, terminal, Git, browser preview, and agent chat sit in one window. Open a project, tell it what you need, and it reads files, writes code, runs commands, and commits. I have been on it since launch. v3.2 finally feels stable enough for real work. Cursor and Windsurf still feel like editors with chat stapled on. Zcode is the opposite: the agent is the product, the UI just follows. Z.AI calls it an "Agentic Development Environment," which is marketing language, but it matches how the app actually behaves. Zcode is now the official development environment from Z.AI for GLM-5.2. It works with GLM Coding Plans and gives you **~1.5x the effective quota** when using Zcode compared to other tools. New users get a **5-day free trial** with 5M tokens/day (3M GLM-5.2 + 2M GLM-5-turbo). ## What Zcode does You interact through natural language, and the agent handles file operations, terminal commands, and browser previews. Here's the workspace you see when you open it: Zcode workspace showing task list, file tree, terminal, and agent chat

Zcode workspace showing task list, file tree, terminal, and agent chat

- **Zcode Agent**: The default agent built for GLM-5.2, with long-task planning, multi-turn context, and continuous code changes across files. - **Goal Mode**: Set a verifiable session objective with `/goal` — the agent keeps iterating until the goal is verified complete. - **Execution Modes**: Five modes from "ask before everything" to "full access" — cycle through them with Shift+Tab. - **Multi-Model Support**: GLM-5.2, Claude, GPT, Kimi K2.5, DeepSeek, or any compatible model. - **Bot Channel**: Connect WeChat or Feishu to control Zcode tasks from your phone's chat app. - **Remote Control**: Scan a QR code to connect your phone to the desktop session and keep tasks moving. - **AGENTS.md Memory**: Project-level instructions file that Zcode reads at the start of every task. ## Installation Zcode is available as a desktop app for macOS, Windows, and Linux (beta). ### macOS 1. Download the DMG from [zcode.z.ai](https://zcode.z.ai/en/docs/install) 2. Open the DMG file 3. Drag **Zcode.app** to your **Applications** folder 4. Launch from Launchpad ### Windows 1. Download the installer from [zcode.z.ai](https://zcode.z.ai/en/docs/install) 2. Double-click the installer 3. Follow the setup wizard ### Linux (Beta) Linux builds are available through the [Feishu beta group](https://applink.feishu.cn/client/chat/chatter/add_by_link?link_token=dabi8911-b0f9-41d8-8090-1b47c058a198). Both x64 and ARM64 AppImages are provided.

How to Create a Carrd Mobile Responsive Navbar (3 Methods)

Thu, 23 Jul 2026 00:00:00 GMT

` entries with your own section links - **Breakpoint**: Change `768px` in the `@media` query to target a different screen width - **Dropdown position**: Adjust `top: calc(15px + 6em)` to match your actual header height - **Transition speed**: Change `0.4s` in `transition: max-height 0.4s ease-in-out` If your nav links point to sections on the same page, add [smooth scrolling for Carrd anchor links](https://www.bitdoze.com/carrd-smooth-scroll/) for a polished UX. ### Accessibility notes The checkbox hack has inherent limitations: it doesn't manage focus properly, and screen readers may interpret the label as a checkbox rather than a button toggle. The updated code includes `role="navigation"`, `aria-label` attributes, and a `