DEV Community: Shubham Sharma

Capstone: Dockerize Your Own App End to End

Shubham Sharma — Sat, 19 Sep 2026 14:00:01 +0000

This is the capstone of the Docker Foundations series. Instead of one new concept, it pulls the whole track together: you take a real app from source code to a live URL served over HTTPS, built into a lean image, hardened the way you would actually run it, pushed to a registry by CI, and deployed to a server. Every command below was run for real, first locally and then on an actual Ubuntu server.

Tip

Get the code: the app, the multi-stage Dockerfile, the production Compose file, the Caddy config, and the CI workflow are in the 10-capstone folder of the companion repo.

Info

Built and run on Docker Engine 29.8.0 with Compose v5.5.1, then deployed on a separate Ubuntu 24.04 server. The output shown is the genuine result.

The app

The app is deliberately small but real: an Express server backed by Postgres. It serves a page with a visit counter (so it has to read and write a database) and exposes a /healthz endpoint for health checks. The full source is in the repo; the only thing that matters here is that it is a normal app with a real dependency, not a toy that prints hello.

A lean image with a multi-stage build

The Dockerfile builds in two stages. The first installs production dependencies against the lockfile; the second copies just those dependencies and the source into a minimal runtime image that runs as a non-root user and declares a healthcheck:

# ---- deps: install production dependencies against the lockfile ----
FROM node:22-alpine AS deps
WORKDIR /app
COPY app/package.json app/package-lock.json ./
RUN npm ci --omit=dev

# ---- runtime: minimal image, non-root, with a healthcheck ----
FROM node:22-alpine AS runtime
ENV NODE_ENV=production
WORKDIR /app
COPY --from=deps /app/node_modules ./node_modules
COPY app/ ./
USER node
EXPOSE 3000
HEALTHCHECK --interval=10s --timeout=3s --start-period=5s --retries=3 \
  CMD wget -q -O /dev/null http://localhost:3000/healthz || exit 1
CMD ["node", "server.js"]

Build it and check the size:

docker build -t tdm-capstone:local .
docker images tdm-capstone:local

tdm-capstone:local  233MB

Because the build tooling stays in the first stage, the final image carries only the Alpine base, the production node_modules, and the app. That is the multi-stage payoff from earlier in the series, applied to a real app.

The production stack

A single Compose file wires the app to Postgres and puts Caddy in front of it, and it turns on the operating and security practices from the rest of the series at once. The important parts:

  app:
    image: ${APP_IMAGE:-tdm-capstone:local}
    depends_on:
      db:
        condition: service_healthy   # do not start until Postgres is ready
    read_only: true                  # the app writes nothing to its own filesystem
    tmpfs:
      - /tmp
    cap_drop:
      - ALL                          # it needs no Linux capabilities
    security_opt:
      - no-new-privileges:true
    healthcheck:
      test: ["CMD-SHELL", "wget -q -O /dev/null http://localhost:3000/healthz || exit 1"]
      interval: 10s
      retries: 3
      start_period: 5s
    deploy:
      resources:
        limits:
          cpus: "0.5"
          memory: 128M

Bring it up, and the health gating sequences the whole stack for you:

docker compose -f compose.prod.yml up -d
docker compose -f compose.prod.yml ps --format "table {{.Service}}\t{{.Status}}"

SERVICE   STATUS
app       Up 23 seconds (healthy)
caddy     Up 18 seconds
db        Up 28 seconds (healthy)

Postgres becomes healthy first, the app waits for it and then becomes healthy itself, and only then does Caddy start. The app answers over HTTPS through Caddy, and the counter proves it is really talking to Postgres:

curl -k https://localhost

<!doctype html>...<p>This page has been served <strong>1</strong> times.</p>...

Hit it again and the count goes to 2. Now confirm the hardening actually took effect, not just that it is written in the file. The container runs as an unprivileged user:

docker compose -f compose.prod.yml exec app id

uid=1000(node) gid=1000(node) groups=1000(node)

Its root filesystem is read-only, so a compromised process cannot rewrite the app, while the /tmp tmpfs stays writable for scratch space:

docker compose -f compose.prod.yml exec app sh -c "touch /oops.txt"

touch: /oops.txt: Read-only file system

And the limits and dropped capabilities are real, straight from docker inspect:

ReadonlyRootfs=true  Memory=134217728  NanoCpus=500000000  CapDrop=[ALL]

That is 128MB of memory, half a CPU, every Linux capability dropped, and a read-only root, on a container that self-reports health. This one stack applies the Compose, volumes, operating, and security posts together.

Ship it: build in CI, push to GHCR

You do not build production images by hand on your laptop. A small GitHub Actions workflow builds the image on every push and pushes it to the GitHub Container Registry, authenticating with the token GitHub gives the job:

permissions:
  contents: read
  packages: write
jobs:
  build-push:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: docker/setup-buildx-action@v3
      - uses: docker/login-action@v3
        with:
          registry: ghcr.io
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}
      - uses: docker/build-push-action@v6
        with:
          context: ./10-capstone
          push: true
          tags: ghcr.io/<you>/tdm-capstone:latest

Pushing this to the repo ran the job green in about half a minute and published the image with its digest:

build-push  in 26s
pushing manifest for ghcr.io/<you>/tdm-capstone:latest@sha256:d6e8d6b6...

Your server can now pull a known, immutable image by tag or digest instead of building on the box. New images published this way are private by default, so to pull one on a server you would first run docker login ghcr.io (or make the package public in your GitHub package settings).

Deploy it with automatic HTTPS

The last step is a real server. Copy this folder up, set the environment, and run the same Compose file. The one new idea is the hostname: sslip.io is a free wildcard DNS service where a name like 203-0-113-5.sslip.io resolves to 203.0.113.5, which gives you a real hostname for any IP without buying a domain. Caddy uses that hostname to request a certificate:

# .env on the server
SITE_ADDRESS=<your-server-ip-with-dashes>.sslip.io

docker compose -f compose.prod.yml up -d
curl -k https://<your-server-ip-with-dashes>.sslip.io

<!doctype html>...<p>This page has been served <strong>1</strong> times.</p>...

That is the app, built from the same Dockerfile, running behind Caddy and answering over HTTPS at a real hostname, on a real server.

Warning

About the certificate: the lab server here has a private IP, which Let's Encrypt cannot reach to validate, so this deploy used Caddy's tls internal option (a local certificate authority) to prove the HTTPS path end to end. On a real VPS with a public IP, you delete the tls internal line and Caddy fetches a genuine, browser-trusted Let's Encrypt certificate for your sslip.io hostname automatically, with no domain purchase and no manual certbot step.

Tear it down

Everything is disposable, which is the point:

docker compose -f compose.prod.yml down -v

That stops and removes the containers, the network, and the named volumes.

What you built

You took an app with a database and turned it into a lean, non-root, resource-limited, health-checked image; ran it as a hardened stack behind a reverse proxy with HTTPS; had CI build and publish it to a registry; and deployed it to a server reachable over HTTPS with no domain purchase. That is the entire Docker Foundations series in one project.

If you worked through the whole track, from installing Docker and running your first containers, through Compose, lean images, volumes and networks, operating, and security, you now have every piece it takes to ship a container you built yourself. That is a genuinely production-shaped skill set, and everything here is in the companion repo for you to clone and run.

Docker Images vs Containers, Explained

Shubham Sharma — Mon, 14 Sep 2026 10:15:47 +0000

If you are new to Docker, this is probably the first thing that trips you up: people say "image" and "container" like they mean the same thing, and they absolutely do not. Getting this one distinction straight makes almost everything else about Docker click into place.

Here is the whole idea in one sentence: an image is the read-only template, and a container is a running copy made from it. If you have written any code, it is the same relationship as a class and an object, or a recipe and the meal you cook from it. One image, many containers.

Info

Everything below was run on a real Docker Engine (Server 29.8.0). The image IDs, container IDs, and sizes are the genuine output. The tables are trimmed to the columns that matter here, so what you see on your own machine will have a few more columns.

One image, many containers

Let's prove the relationship instead of just asserting it. First, pull an image once:

docker pull nginx:alpine

Now start three containers from that single image:

docker run -d --name c1 nginx:alpine
docker run -d --name c2 nginx:alpine
docker run -d --name c3 nginx:alpine

There is still only one image on disk:

docker images nginx

REPOSITORY   TAG      IMAGE ID       SIZE
nginx        alpine   72ba65eb42c1   104MB

But there are three separate containers, each with its own container ID, all pointing back at that same image:

docker ps

CONTAINER ID   IMAGE          NAMES
f291e8935b87   nginx:alpine   c3
dbbf21ab18e1   nginx:alpine   c2
01da24bab3c5   nginx:alpine   c1

One image (72ba65eb42c1), three containers (01da..., dbbf..., f291...). That is the core fact: the image is the shared, unchanging original, and each container is an independent running instance of it. This is exactly why Docker is efficient. Ten copies of the same app do not mean ten copies of its files on disk. They share one image.

Tip

Two quick commands map cleanly onto the two concepts: docker images lists your images (the templates), and docker ps lists your running containers (the instances). If you ever lose track of which is which, that pair is the tell.

Each container gets its own writable layer

If they all share one read-only image, how can containers be different from each other? Because when a container starts, Docker adds a thin writable layer on top of the image, just for that container. Anything the container changes goes into its own layer and touches nothing else.

Watch it happen. Write a file inside c1:

docker exec c1 sh -c "echo 'written inside c1' > /note.txt"
docker exec c1 cat /note.txt

written inside c1

Now look for that same file in c2, which was started from the identical image:

docker exec c2 cat /note.txt

cat: can't open '/note.txt': No such file or directory

The file exists in c1 and does not exist in c2, even though both came from the same image. Each container's changes live in its own private writable layer. The image underneath never changed.

Warning

That writable layer is created and destroyed with the container. Run docker rm c1 and the note.txt you wrote is gone for good. This is the number one surprise for beginners: data written inside a container is not permanent. When you need data to survive, you use a volume, which is the subject of its own guide in this series.

So what is an image, really?

An image is not one big blob. It is a stack of read-only layers, each one a set of filesystem changes from the step that built it. You can list them with docker image history. It prints newest layer first, so here are the top few (the --format flag just trims it to size and command for readability):

docker image history nginx:alpine --format "{{.Size}}\t{{.CreatedBy}}" | head -6

51.8MB   RUN /bin/sh -c set -x   && apkArch="$(cat ...
0B       ENV ACME_VERSION=0.4.1
0B       ENV NJS_RELEASE=1
0B       ENV NJS_VERSION=1.0.1
0B       CMD ["nginx" "-g" "daemon off;"]
0B       STOPSIGNAL SIGQUIT

Each line is a layer. Some add real files and have a size (the 51.8MB package install), others just set metadata like an environment variable or the default command and cost nothing. This is only the top of the list; the base Alpine layer and the rest of the image sit below these, which is where most of the 104MB actually lives. Every container you run from this image shares all of those read-only layers and simply adds its own empty writable layer on top. That shared design is why the three containers above cost you 104MB of image once, not 104MB three times.

The mental model to keep

Line the two up side by side and the distinction sticks:

An image is built, versioned, and read-only. You create it with a Dockerfile, tag it, push it to a registry, and pull it. It is the same for everyone who pulls it.
A container is run, started, stopped, and thrown away. It is one live instance of an image, with its own ID, its own writable layer, and its own lifecycle.

The commands follow the same split. docker build and docker pull deal in images. docker run, docker stop, and docker rm deal in containers. And docker run is simply the bridge between them: it takes an image and produces a running container.

Once that lands, the rest of Docker is mostly detail. Next in the Docker Foundations series, put it to work by running your first containers hands-on, then move up to Docker Compose to run several at once.

Fix: Permission Denied on the Docker Daemon Socket

Shubham Sharma — Mon, 14 Sep 2026 10:15:46 +0000

You ran a normal docker command on Linux and got this instead of output:

permission denied while trying to connect to the docker API at unix:///var/run/docker.sock

On older Docker versions the same problem reads a little differently, but it is the exact same wall:

Got permission denied while trying to connect to the Docker daemon socket at unix:///var/run/docker.sock

Nothing is broken. Docker is running fine. Your user account just is not allowed to talk to it yet. This guide shows you why that happens, the one-line fix that gets you working right now, the permanent fix, and the one "fix" you should never copy from a random forum answer.

Info

Everything below was run on a real Docker Engine (Client 29.8.0 / Server 29.8.0) on Ubuntu 24.04.5 LTS. The commands and output are the genuine results, not illustrations.

Why this happens

Docker does its real work in a background service (the daemon) that runs as root. Your docker command is just a client. It talks to the daemon through a Unix socket, a special file at /var/run/docker.sock. Look at who owns that file:

ls -l /var/run/docker.sock

srw-rw---- 1 root docker 0 Sep 10 15:41 /var/run/docker.sock

Read that line right to left. The socket is owned by user root and group docker, and its permissions are rw for the owner, rw for the group, and nothing for everyone else. So only root and members of the docker group can read from or write to it. A brand-new user is in neither:

id

uid=1000(tester) gid=1000(tester) groups=1000(tester)

No docker group in that list, so the connection is refused. That is the whole story. The error is a file-permission error wearing a scary costume.

Fix 1: run it right now with sudo

If you just need the command to work this second, run it as root with sudo:

sudo docker ps

NAMES     STATUS

The command connects and returns cleanly (an empty table here just means no containers are running). This is fine for a one-off, but typing sudo before every docker command gets old fast, and it means every container you start is being managed as root. For your own machine, set up the permanent fix instead.

Fix 2: add your user to the docker group (the real fix)

Add your user to the docker group once, and you never need sudo for Docker again:

sudo usermod -aG docker $USER

-aG means "append to this group" (the -a matters; without it you would replace all your other groups). Confirm it took:

id

uid=1000(tester) gid=1000(tester) groups=1000(tester),990(docker)

There is the docker group. But if you try docker ps in the same terminal, you may still get permission denied, and this is the step everyone trips on.

Warning

Group membership is only read when a login session starts. Your current shell was started before you joined the group, so it still has your old group list. You need a fresh session for the change to apply.

Get a fresh session in any one of these ways:

# option A: load the new group into the current shell right now
newgrp docker

# option B: log out and back in (or close and reopen your terminal)

# option C: over SSH, disconnect and reconnect

After that, Docker works as your normal user, no sudo:

docker ps

NAMES     STATUS

Connected, no permission error, no sudo. That is the fix you want.

The "fix" to avoid

Search this error and you will find answers telling you to just open up the socket:

# do NOT do this
sudo chmod 666 /var/run/docker.sock

It makes the error go away, and it is a genuinely bad idea. 666 lets every user and process on the machine read and write the Docker socket. Anyone who can talk to the Docker daemon can start a container that mounts your entire host filesystem as root, which is effectively handing them root on the box. The docker group already gives your user that same power, so understand what you are joining.

Error

Adding a user to the docker group (or opening the socket) grants root-equivalent access to the whole machine. That is expected and documented, but it means you should only do it for accounts you fully trust. On shared or production servers, prefer rootless Docker or calling Docker through sudo with a controlled sudoers rule.

Quick reference

# see who owns the socket (root:docker, group-only access)
ls -l /var/run/docker.sock

# right now, one-off
sudo docker ps

# permanent: join the group, then start a fresh session
sudo usermod -aG docker $USER
newgrp docker      # or log out and back in
docker ps          # works, no sudo

That is every legitimate way out of this error. If sudo docker ps also fails, your problem is different: the daemon itself is not running. Start it with sudo systemctl start docker and check sudo systemctl status docker.

New to Docker and want the mental model behind all this? Start with our guide on running your first containers, then work through the Docker Foundations series.

Docker Foundations: The Complete Hands-On Series (Install to Production)

Shubham Sharma — Sun, 13 Sep 2026 19:19:28 +0000

Docker is the front door to modern back-end and self-hosting work, and most tutorials drop you in the middle of it. This series does not. It starts from nothing and takes you all the way to an app you built, hardened, and deployed over HTTPS on a real server. Every guide is hands-on, and every command and number in them was run on real Docker and captured, not paraphrased.

Use this page as the map. Work straight down it if you are starting out, or jump to the piece you need.

Info

Every guide in this series is a real lab: the commands, output, image sizes, and errors are genuine, captured on Docker Engine 29.x. The runnable code for each one lives in the companion repo linked at the bottom.

The path, start to finish

1. Install Docker on macOS, Windows (WSL2), and Linux
One guide, three operating systems, ending in a verified docker run hello-world and the post-install checks each OS actually needs.

2. Run Your First Containers
The everyday lifecycle on a real nginx: run, ps, logs, exec, stop, start, and rm, plus the images-versus-containers mental model.

3. Docker Compose: Run a Multi-Service Stack
Move from single containers to a declarative Web plus Postgres plus Redis stack with one docker compose up, wired together over a Compose network.

4. Lean Docker Images: Multi-Stage Builds and Layer Caching
Cut the same app from a 1.62GB image to 233MB with a multi-stage build, and measure exactly why it shrank and why rebuilds get faster.

5. Where Your Data Lives: Volumes, Bind Mounts, and Networks
Make data survive restarts, back up and restore a volume, and connect containers by name on a user-defined network.

6. Operating Containers: Healthchecks, Limits, Restart Policies, and Env Config
Turn a working stack into one that behaves in production: health-gated startup, memory and CPU limits, self-healing restarts, and clean env config.

7. Docker Security Basics: Non-Root, Read-Only, Image Scanning, and Secrets
Harden a container without breaking it: scan for CVEs, run as non-root, mount the root filesystem read-only, drop capabilities, and keep secrets out of images.

8. Docker vs Podman: A Hands-On Comparison and Migration
Run the same images and Compose file under both engines to see what daemonless and rootless really change, and what it takes to migrate.

9. Capstone: Dockerize Your Own App End to End
Put it all together: a lean image, a hardened Compose stack, a CI build that pushes to a registry, and a deploy behind Caddy with automatic HTTPS.

Quick answers

Two short reads that clear up the questions almost everyone hits early:

Docker Images vs Containers, Explained proves the difference with real output: one image, many containers, each with its own writable layer.
Fix: Permission Denied on the Docker Daemon Socket explains the error every Linux beginner sees and the one permanent fix (plus the insecure one to avoid).

Tip

Get the code: every runnable lab in this series lives in the docker-foundations repo, one folder per post. Clone it and follow along.

Where to start

If you are new, begin at step 1 and go in order; each post builds on the last. If you already run containers, jump to Compose, security, or the capstone. By the end you will be able to build a lean image, run it as a hardened stack, and ship it to a server over HTTPS, all with tools you understand because you ran every step yourself.

LM Studio Guide: Run Local LLMs on Your Mac Fast

Shubham Sharma — Tue, 01 Sep 2026 13:56:57 +0000

LLMs are rapidly changing how we interact with technology, and thankfully, you don't need a supercomputer or a cloud subscription to experiment with them. LM Studio is a desktop application that lets you download and run a vast array of large language models right on your Mac. This guide will walk you through everything from understanding why you'd want to run models locally to getting your first AI model up and running.

What is LM Studio and Why Run AI Models on Your Mac

LM Studio is a game-changer for anyone curious about AI. It's a beautifully designed, user-friendly desktop application that simplifies the process of downloading, discovering, and running large language models (LLMs) directly on your computer. Think of it as an app store for AI, but instead of games or productivity tools, you're downloading powerful AI models that can generate text, write code, answer questions, and much more.

Privacy and Control Without the Cloud

One of the biggest advantages of running AI models locally with LM Studio is the unparalleled privacy and control you gain. When you use cloud-based AI services, your prompts and data are sent to remote servers, where they might be stored, analyzed, or used for training. With LM Studio, everything happens on your machine.

Running models locally means your conversations, your code snippets, and your sensitive data never leave your computer. This is a massive win for privacy-conscious users and developers who handle proprietary information.

This local execution also means you're not reliant on external APIs that can change their terms, pricing, or availability without notice. You have direct access to the AI's capabilities whenever you need them, internet connection or not.

What You'll Be Able to Do After Setup

Once LM Studio is up and running, a whole new world of AI-powered possibilities opens up on your Mac. You're not just running a demo; you're interacting with powerful AI that can assist you in numerous ways.

Here are just a few things you'll be able to do:

Text Generation: Brainstorm ideas, write blog posts, draft emails, create marketing copy, or even write poetry.
Code Completion: Get intelligent code suggestions, help with debugging, and understand complex code snippets, all within your local environment.
Chatbot Creation: Build your own personal chatbot for specific tasks or general conversation, trained on the models you download.
Summarization: Condense long documents or articles into concise summaries.
Translation: Experiment with language translation capabilities.
Creative Writing: Develop stories, scripts, or game narratives.

Tip

The beauty of LM Studio is its flexibility. You can swap out models easily, experiment with different AI personalities, and tailor the experience to your exact needs.

Check Your Mac's Readiness Before Installing

Before you dive into downloading LM Studio, it's crucial to ensure your Mac is up to the task. Running large language models, even locally, can be resource-intensive. Understanding your system's capabilities will help you set realistic expectations and avoid potential performance issues.

Minimum vs. Recommended Specs

The performance of AI models heavily depends on your hardware. While LM Studio can technically run on a range of Macs, some configurations will offer a much smoother experience than others.

Component	Minimum Specs (Basic Functionality)	Recommended Specs (Smooth Experience)	Notes
RAM	8 GB	16 GB or more	More RAM allows for larger models and faster processing.
Storage	50 GB free space	100 GB+ free space	Models can be several gigabytes each.
Processor	Intel Core i5 or Apple M1 (base)	Apple M1 Pro/Max/Ultra, M2, M3 series (or higher Intel)	Apple Silicon (M-series) chips offer significant performance advantages.
GPU	Integrated Graphics	Dedicated GPU (if available) or Apple Silicon GPU	GPU acceleration dramatically speeds up inference. LM Studio leverages Metal on macOS.

How to Check Your Mac's Specs

You don't need to be a terminal wizard to find out what kind of Mac you have. Here's a simple way to check your system details:

Click the Apple Menu: In the top-left corner of your screen, click the Apple icon ().
Select "About This Mac": This will open a window with a summary of your Mac's hardware and software.
Check Overview Tab: Look for information on your "Processor" (e.g., Apple M1, Intel Core i7), "Memory" (your RAM), and "Graphics."
Check Storage: Click on the "Storage" tab to see how much free space you have.
For More Detail: Click "System Report..." for a more in-depth look at your hardware.

Info

If your Mac has Apple Silicon (M1, M2, M3 chips), you're in a great position. These chips are highly optimized for AI tasks and will generally provide a much better experience than older Intel Macs with equivalent RAM.

Download and Install LM Studio on Your Mac

Now that you've confirmed your Mac is ready, let's get LM Studio installed. The process is straightforward and designed to be as user-friendly as possible.

Getting the Installer from the Official Source

Always download software from official sources to ensure you're getting a legitimate and malware-free copy.

Tip

Head over to the official LM Studio website: lmstudio.ai. You'll find download buttons prominently displayed. Choose the version appropriate for your Mac (usually an .dmg file).

Running the Installation Wizard

Once you've downloaded the .dmg file, the installation is usually as simple as dragging the application icon to your Applications folder.

Open the .dmg file: Double-click the downloaded file. A Finder window will typically appear.
Drag to Applications: Drag the LM Studio application icon into the "Applications" folder shortcut within that window.
Eject the disk image: After copying, you can eject the LM Studio disk image by dragging its icon from the Finder sidebar to the Trash.
Launch LM Studio: Open your Applications folder and double-click the LM Studio icon. You might see a security warning; if so, click "Open."

Verify Installation and Launch for the First Time

After launching, LM Studio will present its main interface. For the first launch, it might take a moment to load. You'll see a clean dashboard with options to search for models, chat, and view settings. This confirms that the installation was successful and LM Studio is ready to go.

Download Your First AI Model Inside LM Studio

The real magic of LM Studio is its integrated model browser. Instead of hunting for models across the web, you can discover and download them directly within the application.

Understanding Model Sizes and What They Mean

You'll see models listed with numbers like "7B," "13B," or "70B." This refers to the number of parameters the model has, which is a rough indicator of its complexity and capability. Larger models are generally more powerful but require more resources (RAM and processing power).

You'll also encounter terms like "quantization." This is a process that reduces the precision of the model's weights, making it smaller and faster to run, often with a negligible impact on quality. Common quantization formats include GGUF (used by llama.cpp, which LM Studio leverages) with variations like q4_K_M or q5_K_S.

Model Size	Parameters	Resource Needs	Quality	Best For
7B	7 Billion	Low to Moderate	Good	Beginners, basic tasks, systems with 8-16GB RAM.
13B	13 Billion	Moderate to High	Very Good	Systems with 16GB+ RAM, more complex tasks.
70B	70 Billion	Very High	Excellent	High-end systems with 32GB+ RAM, demanding tasks.

For your first model, start small. A 7B or 13B model is usually a safe bet for most modern Macs.

Recommended Starter Models for Mac

Here are a few models that are often well-regarded and perform nicely on Mac hardware:

Mistral 7B Instruct: A very capable 7B model that balances performance and quality.
Llama 3 8B Instruct: Meta's latest offering, known for its strong performance and instruction-following.
OpenHermes 2.5 Mistral 7B: A fine-tuned version of Mistral, often praised for its conversational abilities.

Downloading a Model Step by Step

Let's get your first model downloaded:

Navigate to the Search Tab: In LM Studio, click the magnifying glass icon on the left sidebar to go to the model search.
Search for a Model: Type the name of a model (e.g., "Mistral 7B Instruct") into the search bar.
Select a Specific Version: You'll see a list of available GGUF files. Look for one with a Q in its name (e.g., mistral-7b-instruct-v0.2.Q4_K_M.gguf). The Q4_K_M indicates a good balance of size and quality.
Click Download: Click the download button next to the model file you've chosen. You'll see the download progress in the bottom section of the app.

Info

Model downloads can take a while depending on your internet speed and the model size. Be patient!

Load Your Model and Start Chatting

With a model downloaded, the next step is to load it and start interacting. LM Studio makes this incredibly simple.

Loading the Model into Memory

Once the download is complete, you need to load the model into LM Studio's inference engine.

Go to the Chat Tab: Click the chat bubble icon on the left sidebar.
Select Your Model: At the top of the chat interface, you'll see a dropdown menu labeled "Select a model to load." Click it and choose the model you just downloaded.
Wait for Loading: LM Studio will now load the model into your Mac's RAM. You'll see a progress indicator. This can take anywhere from a few seconds to a couple of minutes, depending on the model size and your system's speed.

Your First Prompt and Response

Once the model is loaded, the chat interface is ready. Simply type your question or prompt into the message box at the bottom and press Enter. The model will then generate a response.

Basic Settings to Tweak (Temperature, Context)

You'll notice a settings panel on the right side of the chat interface. While you can explore these later, two key parameters to be aware of are:

Temperature: Controls the randomness of the output. Lower temperatures (e.g., 0.2) lead to more focused and deterministic responses, while higher temperatures (e.g., 0.8) produce more creative and varied output.
Context Length: This determines how much previous conversation the model remembers. A larger context window allows for longer, more coherent conversations but uses more RAM.

Here are some common settings to experiment with:

Temperature: Start around 0.7 for general chat.
Top-K / Top-P: These are sampling strategies that also influence output creativity. Defaults are often fine to start.
Max new tokens: Limits the length of the model's response.
Context Length: Adjust based on your RAM. For smaller models, you might be able to increase this significantly.

Tip

Don't be afraid to experiment! Changing these settings can dramatically alter the model's behavior.

Troubleshooting Common Installation and Setup Issues

Even with user-friendly tools, you might run into a snag or two. Here are solutions to some common problems.

App Won't Launch or Crashes on Startup

If LM Studio refuses to open or quits unexpectedly right after launching, it's often due to permissions or installation conflicts.

Troubleshooting App Launch Issues

Re-download LM Studio: The installer might have been corrupted during download. Try downloading it again from lmstudio.ai.
Check macOS Version: Ensure your macOS is up-to-date. LM Studio has minimum OS requirements.
Delete and Reinstall: Drag LM Studio from your Applications folder to the Trash, then empty the Trash. Re-download and install it again.
Permissions: While less common for simple drag-and-drop installs, ensure LM Studio has necessary permissions if prompted.

Model Downloads Fail or Run Out of Disk Space

This is usually a straightforward storage issue.

Troubleshooting Download Failures

Check Available Disk Space: Go to "About This Mac" -> "Storage" to see how much free space you have. Models can be several gigabytes.
Pause and Resume: Sometimes, pausing the download and then resuming it can help.
Clear Cache: LM Studio has a cache for downloaded models. You can manage this in the Settings tab to free up space if needed.
Download Smaller Models: If space is tight, opt for smaller models or more heavily quantized versions.

Responses Are Slow or Model Won't Load

Performance issues are typically related to hardware limitations.

Troubleshooting Slow Performance

RAM is Key: If the model won't load or responses are extremely slow, you might not have enough RAM for that specific model.
Close Other Applications: Free up RAM by closing any unnecessary applications running in the background.
Try a Smaller Model: A 7B model will always be faster and easier to load than a 70B model.
GPU Acceleration: Ensure GPU acceleration is enabled in the settings if your Mac supports it (which most modern Macs with Apple Silicon do). LM Studio usually handles this automatically.

Q: Why is my model download so slow?
A: Download speed depends heavily on your internet connection and the server load on the model hosting platform. Larger models naturally take longer.

Q: Can I run multiple models at once?
A: LM Studio is designed to run one model for inference at a time. You can download many models, but only one can be loaded into memory for chatting.

Q: What's the difference between GGUF and other model formats?
A: GGUF is a file format optimized for running LLMs efficiently on consumer hardware, particularly using libraries like llama.cpp, which LM Studio relies on.

What You Can Build and Do Next with LM Studio

You've got LM Studio installed, a model downloaded, and you've had your first chat. What's next? LM Studio isn't just for casual chatting; it's a powerful tool for developers and creators.

Text Generation and Content Creation

Leverage LM Studio for all your writing needs.

Brainstorming: Ask for blog post ideas, marketing slogans, or story concepts.
Drafting: Generate first drafts of articles, emails, or social media posts.
Editing: Get suggestions for improving clarity, tone, or grammar.

Code Completion and Programming Assistance

Developers will find LM Studio invaluable for local coding tasks.

Code Snippets: Ask for boilerplate code or examples for specific functions.
Debugging Help: Paste error messages or code blocks and ask for potential explanations or fixes.
Learning New Languages: Request explanations of syntax or concepts in a programming language you're learning.

Building Chatbots and Conversational Interfaces

LM Studio can act as the backend for your own applications.

Local API: LM Studio can expose a local OpenAI-compatible API. This means you can point your existing AI applications or scripts to LM Studio instead of a cloud service.
Custom Tools: Build specialized chatbots for customer support, internal knowledge bases, or personal assistants.

Experimenting with Prompt Engineering

The quality of AI output is heavily influenced by how you prompt it.

Iterate: Try different phrasings, add context, or specify the desired output format.
Few-Shot Learning: Provide examples within your prompt to guide the model's response style.
Role-Playing: Instruct the model to act as a specific persona for tailored responses.

Success

By running these models locally, you're not just experimenting with AI; you're building a foundation for powerful, privacy-preserving applications.

Ready to Go Deeper with LM Studio

You've successfully set up LM Studio and run your first AI model. This is just the beginning of your journey into local AI.

Explore More AI Possibilities

Ready to dive deeper? Explore LM Studio's documentation to learn about advanced settings, custom model configurations, and integrating with other tools.

Discover Advanced Features

Running Local LLMs with RamaLama and Docker on a Mac: A Hands-On Guide

Shubham Sharma — Mon, 31 Aug 2026 12:24:50 +0000

RamaLama runs large language models as OCI containers, so a single command (ramalama run smollm:135m) pulls a model and starts talking to it, with no Python environment to babysit. I spent an afternoon putting it through its paces on an Apple Silicon Mac (Apple M4 Pro, 48 GB RAM, macOS 26.6) with Docker 29.4 provided by OrbStack. This guide is what I actually saw: the install, the first model, an OpenAI-compatible server, and the one macOS-specific catch that isn't obvious from the docs. Every command and number below is from that run, on RamaLama 0.24.0.

What is RamaLama?

RamaLama is an open-source CLI from the container-tooling community that treats models like container images. Instead of assembling an inference stack yourself, it pulls a hardened OCI image containing llama.cpp (or vLLM/MLX) plus your chosen model and runs it with Podman or Docker. If you've used Ollama the ergonomics feel familiar (run, serve, list, pull), but the runtime and model live inside containers you can inspect and sign, and weights come straight from Hugging Face, Ollama, or any OCI registry.

Installing RamaLama on macOS

With Homebrew it's one command:

brew install ramalama

That pulled RamaLama 0.24.0 and, notably, its own copy of llama.cpp, ggml, and libomp as dependencies. Hold onto that detail; it matters for GPU acceleration later. Confirm the install:

ramalama version
# ramalama version 0.24.0

You also need a container engine running. I used Docker through OrbStack; Podman works too and is RamaLama's default on Linux.

Running your first model

The headline command:

ramalama run smollm:135m "In one sentence, what is a Linux container?"

Passing a prompt as an argument gives you one-shot output instead of dropping into a chat REPL. On first run this pulled the RamaLama container image, downloaded the model, and answered. smollm:135m resolves to hf://HuggingFaceTB/smollm-135M-instruct-v0.2-Q8_0-GGUF, a 138 MB, 8-bit quantized GGUF from Hugging Face.

First-run wall-clock was 2 minutes 56 seconds, but almost all of that was downloads (the ~1 GB image plus the model); the 135M model itself is near-instant on CPU. It is also not smart: asked about containers it invented "2048-bit containers" and a docker-compose up -v command that doesn't exist. That's expected at 135M parameters. Use a model this small to validate your setup, not to do real work; a 1B model like llama3.2:1b (a 770 MB Q4_K_M download) answers the same question correctly. (For which models are actually worth running today, see the open-weight coding leaderboard shake-up.)

Check what you've downloaded:

ramalama list
# SHORTNAME    NAME                                                    SIZE
# llama3.2:1b  hf://bartowski/Llama-3.2-1B-Instruct-GGUF               770.28 MB
# smollm:135m  hf://HuggingFaceTB/smollm-135M-instruct-v0.2-Q8_0-GGUF  138.1 MB

Models live under ~/.local/share/ramalama, separate from your container images.

What RamaLama actually runs

Before running anything for real, --dryrun prints the exact command without executing it:

ramalama --dryrun run smollm:135m "hi"

On my Mac that expands to a hardened docker run:

docker run ... --security-opt=label=disable --cap-drop=all \
  --security-opt=no-new-privileges --pull always -d -p 8080:8080 \
  --init quay.io/ramalama/ramalama:0.24 \
  llama-server --host :: --port 8080 --model /path/to/model --threads 7 ...

Note what it does by default: drops all Linux capabilities, disables privilege escalation, and starts llama-server, the same server that backs the OpenAI-compatible API below. The base image (quay.io/ramalama/ramalama:0.24) is about 1 GB, downloaded once and reused.

The macOS gotcha: containers run on the CPU

Here is the part that trips people up. On Apple Silicon, a model running inside a Linux container cannot reach the Mac's GPU, because Docker's Linux VM has no path to Metal. ramalama info reports the container engine's accelerator as none:

{ "Accelerator": "none", "Config": { "runtimes": { "llama_cpp": {}, "mlx": {} } } }

So the default containerized run is CPU-only. Fine for a 135M toy, painful for anything larger. The fix is --nocontainer, which runs the host's llama.cpp (the copy Homebrew installed) directly:

ramalama --nocontainer serve -p 8081 llama3.2:1b

I benchmarked the difference on the same model and prompt. Served natively, Llama-3.2-1B (Q4_K_M) loads straight onto the Apple GPU. Its startup log shows:

load_tensors: offloaded 17/17 layers to GPU
ggml_metal_init: found device: Apple M4 Pro

and it generated at ~206 tokens/sec. The same model served in the default container has no GPU to offload to and ran at ~102 tokens/sec on the CPU, about half the speed on this M4 Pro. RamaLama also exposes an mlx runtime if you'd rather use Apple's own inference framework than llama.cpp.

Mode	Command	Isolation	Acceleration	Llama-3.2-1B
Container (default)	`ramalama run`	Full (OCI, cap-drop)	CPU only	~102 tok/s
Native	`ramalama --nocontainer run`	None	Apple GPU (Metal) / MLX	~206 tok/s

The trade-off is genuine: containers give you isolation and reproducibility; native gives you the GPU. On a Mac doing real work, --nocontainer is usually what you want. On Linux with an NVIDIA GPU, the container path keeps both.

Serving an OpenAI-compatible API

This is where RamaLama earns its place. serve starts the same llama-server as a local endpoint:

ramalama serve -d --name tdm-lab -p 8080 smollm:135m

It speaks the OpenAI API, so anything that talks to OpenAI can point at it:

curl http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"model":"smollm","messages":[{"role":"user","content":"Say hello."}]}'

The response is standard OpenAI JSON: choices[].message.content, a usage block, and timings. Swap the base URL in your existing OpenAI client and your app runs locally with no code changes. Stop it when done:

ramalama stop tdm-lab

If you'd rather wire a local endpoint into your editor, the same idea powers our guide on connecting Copilot Chat to a local API.

So, is RamaLama worth it?

If you already live in containers, yes. Its strengths are the security defaults (cap-drop, no-new-privileges, signed OCI images), pulling from Hugging Face, Ollama, and OCI registries interchangeably, and the zero-friction OpenAI server. If you just want the fastest local chat on a Mac with a GUI, LM Studio is gentler. The two aren't mutually exclusive: I keep LM Studio for exploring and RamaLama for scripting reproducible, servable model runs.

Plan for two things before you graduate from the toy model. Pick a real quantized model that fits your RAM (a 7–8B Q4 model wants roughly 6–8 GB free), and on a Mac decide up front whether you're optimizing for isolation (container, CPU) or speed (native, Apple GPU).

Key takeaways

Install: brew install ramalama (bundles llama.cpp); needs Docker or Podman running.
Run: ramalama run <model> "prompt" for one-shot output; models come from Hugging Face, Ollama, or OCI registries.
Inspect first: ramalama --dryrun run <model> prints the exact hardened docker run.
macOS catch: containerized runs are CPU-only; --nocontainer offloads to the Apple GPU (Metal). On this M4 Pro, Llama-3.2-1B ran ~206 tok/s native versus ~102 tok/s in-container, about 2x faster.
Serve: ramalama serve exposes a drop-in OpenAI-compatible API on port 8080.
Tested with RamaLama 0.24.0 on macOS 26.6 (Apple M4 Pro, 48 GB), Docker 29.4 via OrbStack; models smollm:135m and llama3.2:1b (Q4_K_M).

Put SSH Behind Tailscale and Close Port 22

Shubham Sharma — Mon, 31 Aug 2026 10:11:49 +0000

Once a VPS is hardened the usual way, keys only, firewalled, patched, there is a bigger move you can make: stop exposing SSH to the public internet at all. Instead of trusting that a strong key holds up against constant scanning, you put SSH on a private network the rest of the world cannot even see, and close port 22 to everyone else. This is my favorite upgrade for a small server in 2026, and it is genuinely less fragile than it sounds, as long as you keep one escape hatch.

This guide picks up where Setting Up Your Own VPS leaves off. If you have not done the baseline (non-root user, SSH keys, UFW), start there first.

Key takeaways

Tailscale gives your server a private address that only your own devices can reach.

Disable key expiry on the server in the admin console, or Tailscale logs you out in 180 days and you cannot reauth remotely.

Allow the tailscale0 interface in UFW, then remove the public port 22 rule.

Always test a new connection over Tailscale before you close the old one.

Keep your provider's browser console handy as a recovery path.

What "behind Tailscale" actually means

Tailscale builds a private mesh network (a "tailnet") between your machines using WireGuard. Every device you add gets a stable 100.x address that is reachable only by your other devices, never from the open internet. Put your server and your laptop on the same tailnet and you can SSH to the server over that private address. Once that works, public port 22 has no reason to exist, so you close it.

There are two ways to run SSH over the tailnet, and it is worth knowing which you are choosing:

Plain OpenSSH over Tailscale. You keep using normal OpenSSH and simply reach it through the private address. Your existing keys and hardening still apply. This is what I recommend for most people, because nothing about your battle-tested SSH setup changes.
Tailscale SSH. Tailscale's own daemon answers on port 22 of the tailnet address and authenticates with your Tailscale identity and access rules. It is convenient, especially for teams, but it hands authentication to Tailscale instead of OpenSSH. Reasonable people disagree here; pick based on how much you want to lean on one provider.

Either way, the firewall move is the same.

Step 1: Install Tailscale and connect

On the server, install Tailscale and bring it up. The install script supports every mainstream distro:

curl -fsSL https://tailscale.com/install.sh | sh
sudo tailscale up

The command prints a URL. Open it, sign in, and the server joins your tailnet. Install Tailscale on your laptop the same way and sign in with the same account. Check the server's private address with:

tailscale ip -4

You will get a 100.x.x.x address. From your laptop, confirm plain SSH works over it before changing anything:

ssh deploy@100.x.x.x

If you would rather use Tailscale SSH, enable it without dropping your session:

sudo tailscale set --ssh

Step 2: Disable key expiry (do not skip this)

This is the step people forget, and the one that locks them out. By default Tailscale expires a machine's key after 180 days and asks it to log in again. On your laptop that is a minor prompt, but on a headless server whose only door is Tailscale, it is a lockout you cannot fix remotely.

In the Tailscale admin console, open Machines, find the server, open the "..." menu, and choose Disable key expiry. Do this now, while you are thinking about it, for every server you put behind the tailnet.

Step 3: Let the tailnet through UFW, then close port 22

Now tell the firewall to trust the Tailscale interface and remove the public SSH rule. This order matters. Following Tailscale's own ufw lockdown guide:

# Allow everything arriving over the private Tailscale interface
sudo ufw allow in on tailscale0

# Keep the public web ports if you serve a site; otherwise skip this
sudo ufw allow 80,443/tcp

# Remove the public SSH opening
sudo ufw delete allow OpenSSH

Watch for a leftover blanket rule. If sudo ufw status still lists something like 22/tcp ALLOW IN Anywhere, delete it too:

sudo ufw delete allow 22/tcp

Confirm the rules took effect:

sudo ufw status verbose
sudo ss -tlnp | grep :22

ufw status verbose should show Default: deny (incoming), an ALLOW ... on tailscale0 line, and no rule for port 22. One point that trips people up: sshd keeps listening on 0.0.0.0:22, so ss still shows it there, and that is fine. With this approach UFW is what blocks the public side, not sshd, so you verify by behavior (the next step) rather than by the listen address. If you would rather sshd not listen on the public interface at all, you can add ListenAddress lines for your Tailscale and loopback addresses to the SSH drop-in, but leave that as optional hardening: if the tailnet interface is not up when sshd starts, binding fails, so the firewall rule is the safer primary control.

Step 4: Test before you trust it

Never close your working session until a fresh one succeeds. Keep your current SSH terminal open until you have confirmed a new connection works over the tailnet.

With your current SSH terminal still open, start a new terminal and connect over the tailnet:

ssh deploy@100.x.x.x

If that lands you on the server, public SSH is closed and private SSH works. Now you can close the old session. If it fails, you still have the original terminal to undo the firewall change.

Your safety net if it all goes wrong

Two things keep this from ever becoming a real lockout:

The provider console. Hostinger and most hosts include a browser based terminal in their control panel that reaches the server directly, not over SSH. If Tailscale is ever down or misconfigured, that is how you get in to fix it. This is the recovery path you were told to find in the baseline guide.
The reversal order. If you ever remove Tailscale from the server, re-open public SSH first (sudo ufw allow OpenSSH), or you will delete your only way in.

Is this actually a good idea? The trade-offs

I like this setup, but it is fair to name what you are trading:

You are trusting a third party. Tailscale and its coordination servers become part of your access path. Some people would rather depend only on OpenSSH, which is open source and among the most audited software in the world. That is a legitimate position.
You can own the control plane. If that worries you, run Headscale, an open source implementation of the Tailscale control server, or use NetBird as an alternative mesh. More work, less reliance on one company.
This is remote access, not everything. Public web traffic still needs a plan. You can keep serving 80 and 443 directly, or, to avoid opening even those, put the app behind a tunnel. That is a good topic for its own guide.

If you self-host a handful of services for yourself and value not watching your SSH port get scanned a thousand times a day, this is hard to beat.

Where to go next

Start here if you skipped it: Setting Up Your Own VPS: A Secure Starting Point.
Put something behind the tailnet: admin panels are perfect candidates. In the n8n guide you could keep the editor private on the tailnet and only expose webhooks publicly.

Final thoughts

The mental shift is simple: your server should not answer the door for strangers at all. Give it a private address, let only your own machines knock, and keep one emergency key (the provider console) for the bad day. Do that, and the daily reality of running a public VPS gets a lot quieter.

Verified end to end on a real Ubuntu 24.04.4 server: joined a tailnet, allowed tailscale0 in UFW, and removed the public port 22 rule. From a separate machine, SSH to the public IP then timed out while SSH over the tailnet address still logged in, and the kernel firewall log showed the public SYN dropped on eth0. The reversal step re-opened public SSH cleanly. See the linked lab notes.

Setting Up Your Own VPS: A Secure Starting Point

Shubham Sharma — Mon, 31 Aug 2026 09:39:20 +0000

Every self-hosted project I run starts the same way: a brand new VPS and about twenty minutes of setup before I install a single application. That twenty minutes is what separates "my server" from "someone else's crypto miner." A fresh box with a public IP starts getting probed within minutes, and the default configuration on most images is built for convenience, not safety.

This is the secure baseline I set up on every new server, before Docker, before n8n, before anything else. It is also the starting point our production n8n guide assumes you already have. Every command below was checked against current Ubuntu LTS documentation, and I flag the parts that genuinely need a real server to verify.

Key takeaways

Never do daily work as root. Create a sudo user and log in as that instead.

Use an SSH key and turn password login off, but only after you confirm the key works.

Deny everything at the firewall by default, then open only the ports you actually use.

Turn on automatic security updates so patches land while you sleep.

If you plan to run Docker, remember that published ports skip UFW. Bind them to 127.0.0.1.

Prerequisites

A VPS running a current Ubuntu LTS. Both 24.04 "Noble Numbat" and 26.04 "Resolute Raccoon" work well. I run long-lived boxes on Hostinger VPS hosting, which is also what powers the n8n guide.
An SSH key pair on your own machine. If you do not have one yet, Step 3 creates it.
A terminal, and a note of your provider's recovery console. Most hosts, Hostinger included, give you a browser based console in their control panel. That is your way back in if you ever lock yourself out, so find it before you start.

Disclosure: some links in this guide, including the Hostinger link above, are referral or affiliate links. If you sign up through them we may earn account credit or a commission, at no extra cost to you. We only point at tools we actually run.

Step 1: Log in and update the system

Right after the server boots, log in with the credentials your provider gave you and bring every package up to date:

ssh root@YOUR_SERVER_IP
apt update && apt upgrade -y

If the upgrade pulls a new kernel, reboot with reboot and log back in. Starting from a fully patched system means the rest of this guide is the only thing left between you and a solid baseline.

Step 2: Create a non-root user

Working as root all day is the single most common mistake on a new server. One typo or one bad script runs with full control of the machine. Create a normal user with sudo rights and use that from now on:

adduser deploy
usermod -aG sudo deploy

Swap deploy for whatever name you like. The adduser command asks for a password; pick a strong one, since sudo will ask for it.

Step 3: Set up SSH keys

From your own machine, not the server, create a key if you do not already have one:

ssh-keygen -t ed25519 -C "you@your-machine"

Copy the public half up to the new user, then log in as that user to confirm it works:

ssh-copy-id -i ~/.ssh/id_ed25519.pub deploy@YOUR_SERVER_IP
ssh deploy@YOUR_SERVER_IP

Do not move on until that last command logs you in without asking for the account password. The next step turns password login off completely, and if the key is not working you will lock yourself out.

Step 4: Harden SSH

Now lock SSH down to keys only and stop root from logging in over it. On Ubuntu, the clean way is a drop-in file, so a future package update cannot quietly overwrite your changes. As the deploy user:

sudo tee /etc/ssh/sshd_config.d/99-hardening.conf > /dev/null << 'EOF'
PermitRootLogin no
PasswordAuthentication no
KbdInteractiveAuthentication no
PubkeyAuthentication yes
MaxAuthTries 3
LoginGraceTime 30
X11Forwarding no
EOF

There is one catch that trips people up. SSH reads its settings top to bottom and keeps the first value it finds for each one, and cloud images ship a lower numbered file that sets PasswordAuthentication for you. On Ubuntu 24.04 it is 60-cloudimg-settings.conf, which already sets it to no; older images used 50-cloud-init.conf and sometimes set it to yes. Because a lower numbered file loads first, whatever it says wins over your file. So do not trust the filename alone. Check the effective configuration, which is the real source of truth:

sudo sshd -t   # tests syntax; no output means it is fine
sudo sshd -T | grep -E "permitrootlogin|passwordauthentication|pubkeyauthentication"

You want to see passwordauthentication no and permitrootlogin no in that output. If password auth still says yes, open the offending lower numbered file, comment that line out, and check again. Once it reads correctly, reload SSH (this does not drop your current session):

sudo systemctl reload ssh

Keep your existing terminal open and log in from a second one to be sure. If anything is wrong, the open session is your safety net.

Step 5: Turn on a firewall

UFW is a friendly front end to the kernel firewall. It is present on the desktop and full server images, but a minimal cloud image often does not include it, so install it first (a no-op if it is already there). Then set it to deny everything coming in, allow your own traffic out, and open only SSH and the web ports:

sudo apt install -y ufw
sudo ufw default deny incoming
sudo ufw default allow outgoing
sudo ufw allow OpenSSH
sudo ufw allow 80,443/tcp
sudo ufw enable
sudo ufw status verbose

If you are not serving a website yet, skip the 80,443 line and add it later. The whole idea is that nothing is reachable unless you said so.

Step 6: Automatic security updates

Security patches are only useful once they are installed. The unattended-upgrades package applies them for you:

sudo apt install unattended-upgrades -y
sudo dpkg-reconfigure --priority=low unattended-upgrades

Choose "Yes" at the prompt. You can preview what it would do without changing anything:

sudo unattended-upgrades --dry-run --debug

By default it installs security updates only, which is the sweet spot: you stay patched without surprise changes to everything else on the box.

Step 7: (Optional) Add fail2ban

With password login already off, brute force attempts against SSH are mostly noise, since there is no password to guess. If you still want to trim the log spam, fail2ban watches for repeated failures and bans the source for a while:

sudo apt install fail2ban -y

Its defaults enable an SSH jail out of the box. Treat this as a nicety, not a substitute for keys and a firewall.

The Docker trap almost everyone hits

Here is the one that surprises even experienced people, and it is why it belongs in the baseline.

Docker bypasses UFW. When you publish a container port, Docker writes its own firewall rules that skip UFW entirely. Your ufw status can look locked down while a database sits wide open to the internet.

The reason is where each tool sits in the network path. Docker sends published-port traffic through its own chain before it ever reaches the point UFW inspects, so UFW never gets a say. This is documented behavior, described in Docker's own packet filtering and firewalls page and flagged by the OWASP Docker Security Cheat Sheet.

The simplest, most reliable fix is to bind published ports to localhost instead of every interface. Compare:

# Exposed to the whole internet, even with UFW "on":
ports:
  - "5432:5432"

# Reachable only from the server itself:
ports:
  - "127.0.0.1:5432:5432"

Better still, do not publish internal services at all. Containers on the same Docker network reach each other by name, so a database that only your app talks to needs no host port. That is exactly the pattern in our n8n guide, where Postgres is never published and only Caddy faces the internet.

Where to go next

You now have a server that is patched, key-only, firewalled, and no longer running as root. Two natural next steps:

Take SSH off the public internet entirely. In the next guide I put SSH behind a private Tailscale network and close port 22 to the world: Put SSH behind Tailscale and close port 22.
Run something on it. Our production n8n guide uses this exact baseline as its foundation.

An honest word on trade-offs

None of this makes a server "unhackable," and anyone who tells you a checklist does is selling something. What it does is remove the easy wins: default passwords, root over SSH, exposed services, unpatched holes. That covers the overwhelming majority of automated attacks, which is what actually hits a small VPS. Keep your software updated, keep backups you have tested, and add depth (like the Tailscale step) as your setup grows.

Final thoughts

The shape of this never really changes: a real user, keys not passwords, a default-deny firewall, automatic patches, and an awareness of how Docker treats ports. Do it once, turn it into muscle memory, and every future box takes ten minutes. Then you get to the fun part, which is running your own software.

Verified on a real Ubuntu 24.04.4 server with Docker 29.1.3: the SSH hardening effective values (sshd -T), the default-deny UFW policy, the Docker-bypasses-UFW behavior and the 127.0.0.1 fix (an external request reached the 0.0.0.0-published port straight through an active firewall, then was refused once the port was bound to loopback), automatic security updates, and the fail2ban SSH jail. See the linked lab notes.

Self-Host n8n on a VPS with Docker, PostgreSQL, and Caddy (2026)

Shubham Sharma — Mon, 31 Aug 2026 09:39:17 +0000

I stood this exact stack up before writing a line of it: n8n 2.36.8 talking to PostgreSQL 16.13, fronted by Caddy 2.11.4 for automatic HTTPS. Every command and version below comes from that run. If you have only used the one-line docker run for n8n, this is the production version: a real database instead of the default SQLite, HTTPS without hand-managing certificates, and a layout you can back up and upgrade without losing your workflows.

Key takeaways

Use PostgreSQL, not the default SQLite: set DB_TYPE=postgresdb and the DB_POSTGRESDB_* variables.

Set a persistent N8N_ENCRYPTION_KEY before first launch, or you lock yourself out of saved credentials on the next redeploy.

Let Caddy own HTTPS: point your domain at the server and it provisions a Let's Encrypt certificate automatically.

Verified on n8n 2.36.8, PostgreSQL 16.13, Caddy 2.11.4.

Prerequisites

A VPS (1 vCPU and 2 GB RAM is enough to start) on a recent Linux, with a public IP. New to running a server? Our secure VPS setup guide gets you to a safe baseline first.
A domain or subdomain you control: an A record for n8n.example.com pointing at the VPS.
Docker Engine and the Compose plugin installed. New to Docker? Our RamaLama and Docker walkthrough covers the basics on your own machine first.
Ports 80 and 443 open to the internet (Caddy needs them for HTTPS). Keep 5678 closed.

Heads up: n8n.example.com is a placeholder. Replace it everywhere below (in .env, the Caddyfile, and your DNS record) with a subdomain you actually own, for example n8n.yourdomain.com. example.com is a reserved documentation domain, so it will never issue a TLS certificate.

Step 1: Create the project and secrets

SSH into the VPS, make a directory, and generate two secrets: a database password and n8n's encryption key. The encryption key is the one people forget. n8n uses it to encrypt saved credentials, so if it changes between deploys, every stored credential becomes unreadable.

mkdir -p ~/n8n && cd ~/n8n
{
  echo "POSTGRES_PASSWORD=$(openssl rand -hex 24)"
  echo "N8N_ENCRYPTION_KEY=$(openssl rand -hex 24)"
  echo "N8N_HOST=n8n.example.com"
} > .env
chmod 600 .env

Swap n8n.example.com for your domain.

Step 2: Write the Compose file

Create docker-compose.yml with three services: Postgres (n8n's database), n8n, and Caddy as the HTTPS reverse proxy. Note that n8n's port 5678 is not published to the host; Caddy reaches it over the internal network, so it never faces the internet directly. Every n8n setting used below is documented in n8n's hosting docs.

services:
  postgres:
    image: postgres:16-alpine
    environment:
      POSTGRES_USER: n8n
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
      POSTGRES_DB: n8n
    volumes:
      - pgdata:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U n8n -d n8n"]
      interval: 5s
      timeout: 5s
      retries: 12
    restart: unless-stopped

  n8n:
    image: n8nio/n8n:2.36.8
    depends_on:
      postgres:
        condition: service_healthy
    environment:
      DB_TYPE: postgresdb
      DB_POSTGRESDB_HOST: postgres
      DB_POSTGRESDB_PORT: 5432
      DB_POSTGRESDB_DATABASE: n8n
      DB_POSTGRESDB_USER: n8n
      DB_POSTGRESDB_PASSWORD: ${POSTGRES_PASSWORD}
      N8N_HOST: ${N8N_HOST}
      N8N_PROTOCOL: https
      N8N_PORT: 5678
      WEBHOOK_URL: https://${N8N_HOST}/
      N8N_ENCRYPTION_KEY: ${N8N_ENCRYPTION_KEY}
      N8N_RUNNERS_ENABLED: "true"
      GENERIC_TIMEZONE: UTC
    volumes:
      - n8ndata:/home/node/.n8n
    restart: unless-stopped

  caddy:
    image: caddy:2-alpine
    depends_on: [n8n]
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./Caddyfile:/etc/caddy/Caddyfile
      - caddydata:/data
      - caddyconfig:/config
    restart: unless-stopped

volumes:
  pgdata:
  n8ndata:
  caddydata:
  caddyconfig:

I pinned n8n to 2.36.8, the version I tested, so your deploy matches this guide. Bump it deliberately later rather than tracking latest blindly.

Step 3: Write the Caddyfile

n8n.example.com {
    reverse_proxy n8n:5678
}

That is the entire HTTPS setup. Once your domain resolves to the server and 80 and 443 are reachable, Caddy requests a Let's Encrypt certificate on the first visit and renews it on its own. No certbot, no cron job.

Step 4: Launch and verify

docker compose up -d

Compose starts Postgres first, waits for its healthcheck to pass, then starts n8n, which connects and runs its database migrations. Confirm both:

docker compose ps
docker compose logs -f n8n   # watch the migrations finish, then Ctrl-C

On my run, n8n 2.36.8 came up healthy in about ten seconds once the images were cached, and the log showed it running its migration set against Postgres 16.13. That is exactly what you want to see: n8n is using Postgres, not silently falling back to SQLite. If you temporarily add ports: ["127.0.0.1:5678:5678"] to the n8n service, curl http://localhost:5678/healthz returns {"status":"ok"}. Remove it once Caddy is serving.

Open https://n8n.example.com and n8n prompts you to create the owner account. Do that immediately, before anyone else finds the URL.

Once that is done you land on the workflow editor, ready to build your first automation:

Step 5: Harden it

A few settings separate a demo from something you leave running:

Encryption key: you set N8N_ENCRYPTION_KEY in Step 1. Keep .env backed up somewhere safe; losing it means re-entering every credential by hand.
Firewall: allow only SSH, 80, and 443. On Ubuntu: ufw allow OpenSSH && ufw allow 80,443/tcp && ufw enable. Never expose 5678.
Restart policy: restart: unless-stopped (already in the file) brings the stack back after a reboot.
Stay patched: keep the host updated, and treat n8n version bumps as a deliberate step.

Step 6: Back up and upgrade

Two volumes hold your state: pgdata (workflows, executions, credentials) and n8ndata (n8n's config). Back up both.

# database dump
docker compose exec -T postgres pg_dump -U n8n n8n | gzip > n8n-db-$(date +%F).sql.gz
# n8n data volume
docker run --rm -v n8n_n8ndata:/data -v "$PWD":/backup alpine \
  tar czf /backup/n8n-data-$(date +%F).tar.gz -C /data .

To upgrade, change the pinned tag in docker-compose.yml, then:

docker compose pull n8n
docker compose up -d n8n

n8n runs any new migrations on start. Because your data lives in the Postgres and n8ndata volumes, the container itself is disposable, which is the entire point of running it this way.

Common issues

Credentials read as broken after a redeploy. The N8N_ENCRYPTION_KEY changed. Restore the original key from your .env backup.
The certificate never issues. Caddy needs the domain's A record pointing at the server and ports 80 and 443 reachable. Check docker compose logs caddy for ACME errors.
n8n warns about task runners. n8n 2.x expects N8N_RUNNERS_ENABLED=true, which is already set above.

FAQ

Do I need PostgreSQL, or is SQLite fine? SQLite works for a hobby instance, but for anything you rely on, Postgres handles concurrent executions and backups far better. Switching later is a migration; starting on Postgres avoids it.

Can I use Nginx instead of Caddy? Yes, but Caddy's automatic HTTPS is the reason it is here: one line of config versus managing certbot and renewals.

How much server do I need? A 1 vCPU and 2 GB VPS runs a light instance. Heavy or highly concurrent workflows want more RAM and, eventually, n8n's queue mode with separate worker containers.

Final thoughts

The shape here, an application plus Postgres plus Caddy in one Compose file, is the same one you will reuse for most self-hosted tools. Set the encryption key, let Caddy own TLS, keep your state in named volumes, and upgrades become a two-line routine.

Verified end to end on n8n 2.36.8, PostgreSQL 16.13, and Caddy 2.11.4.