You can name the workload and you know what a VPS demands. One problem remains, and it bites everyone exactly once: the app that works perfectly on your Mac and dies on the server. This lesson packs the suitcase.

"It worked on my machine" is not a deployment plan

The scene: your research app runs beautifully on your MacBook. You copy the files to the VPS (or the dedicated Mac mini), run the same start command — and it crashes. The server has Python 3.11 while you built on 3.13. A system library is missing. An environment variable you set months ago and forgot does not exist there. A dependency resolved differently.

None of this is mysterious. Your app never ran on "Python" in the abstract — it ran on your exact runtime version, your exact system packages, your exact settings, your exact dependency tree. Move machines without moving that context and you changed the app without changing a line of code.

The fix is to ship the context with the code: package the application together with the specific runtime and dependencies it needs, so the same package runs identically on your laptop, the Mac mini, and the VPS. That package is a container, and Docker is the standard way to build and run them.

What a container actually is

A container is a packaged, isolated runtime for one application component. It bundles your application with the specific runtime and libraries it needs, sealed off from whatever else lives on the host machine.

Three distinctions that prevent years of confusion:

• A container is not a whole virtual computer. A VPS virtualizes hardware and runs a full operating system. A container shares the host's OS kernel and isolates just one process and its dependencies. Lighter, faster, narrower.
• A container is not a server. It still needs somewhere to run — your laptop, a Mac mini, a VPS. Docker answers "how does it run identically everywhere," not "where does it run."
• A container is not permanent storage. Containers are disposable by design. Delete one and anything written inside it goes with it. Durable data lives outside — in a database or object storage, as Lesson 24.1's separation already taught.

One sentence to memorize: *the image is the lunchbox, the container is the lunch being eaten, the VPS is the table it sits on, and the database is the pantry.*

The three Docker terms, plainly

Docker has exactly three words you must own:

• Dockerfile — the recipe. A short text file in your project describing how to build the package: start from this base runtime, install these dependencies, copy these files, run this command. Human-readable, version-controlled, reviewable.
• Image — the packaged result. The sealed, portable bundle produced by building the Dockerfile. One image can be copied to any machine and run identically. Versioned like code — research-app:v3 means something precise.
• Container — one running copy. Launch an image and you get a live, isolated process. Run the same image twice and you get two identical, separated copies. Stop and delete a container and the image remains, ready to launch again.

The chain you will use constantly:

Project files + Dockerfile
  → build image
  → run container locally for a check
  → send the same image or build instructions to Mac mini / VPS
  → run the same application there

Build once, verify locally, run the identical artifact remotely. That is the entire discipline. The VPS chapter of "works on my machine" closes the day this chain becomes habit.

Docker's role on a VPS

On a VPS, Docker earns its keep three ways:

1. Predictability. The web app, the worker, the scheduled process, the MCP server — each runs the runtime you tested, not whatever the server happened to have. 2. Separation. One VPS can hold several services without their dependencies fighting. The web layer wants one library version; the worker wants another; each container carries its own. No hand-installing everything into the host OS, no upgrade that breaks the neighbor. 3. Repeatability. A new VPS, a rebuilt VPS, a second VPS — same image, same behavior. Your runbook's restart step becomes "run this image with these settings" instead of a folklore installation saga.

Concretely: your ByeBuy stack might run a web/API container serving visitors, a worker container processing queued documents, and a scheduled container firing the nightly fetch — all on one modest VPS, each isolated, each restartable independently.

Docker's role on a dedicated Mac mini

Same benefits, local address. Docker lets the Mac mini run a project service separately from your personal applications: the agent's MCP server in one container, the collector in another, your everyday browsing and coding untouched outside them. Upgrading a project dependency no longer risks your development environment, and vice versa.

But read the boundary twice: Docker makes deployment repeatable, not magically operational. The Mac mini still needs everything from Lesson 24.2 — power, internet, network path, no sleep, disk space, reboot recovery — plus Lesson 24.3's updates, logs, access controls, and backups. A container does not watch its own disk fill or renew its own certificate. Packing the suitcase does not hire the superintendent.

What Docker does not solve

Say this list out loud before anyone sells you containers as infrastructure:

• Public DNS — naming and routing visitors still needs domain configuration.
• HTTPS by itself — certificates and termination still need setup.
• Database backups — Postgres (or Supabase) still needs its own backup and restore story.
• Secret management — keys still live in environment settings, never baked into images.
• Monitoring — health checks, job-success signals, and alerts still need owners.
• Storage durability — files inside a disposable container are the opposite of durable.
• Security review — images need updating and scanning like any software.
• Choosing the home — Docker never answers "should this run on serverless instead?" That is the workload card's job.

Docker is packing. It is not the address, the locks, the insurance, or the decision to move.

A concrete AI-product layout

Assemble everything into one picture — a small research product, containerized correctly:

• Web/API container serves visitors and the API layer: receives questions, reads prepared facts, returns cited answers.
• Worker container processes queued documents: extracts text, builds chunks and embeddings, updates status rows.
• External Postgres/Supabase holds all durable data: sources, chunks, users, job records.
• Object storage holds original uploads: PDFs, images, exports — with the database storing only paths and metadata.

State lives in the database and object storage. Logic travels in containers. Either container can be deleted and relaunched from its image without losing a single fact — because no state lives inside a disposable container. If your design keeps uploads or database files inside a container, redraw it now.

For local development or a small server, a tool called Docker Compose lets you describe these cooperating containers in one file — web plus worker plus a local database for testing — and start them together. Treat Compose as an orchestration convenience for a small stack, not a production strategy by itself. It simplifies run these three things together; it does not provide backups, monitoring, or scaling.

And the selection rule that keeps Docker in its lane: use Docker when the project needs a portable, repeatable runtime on a VPS or dedicated local server. Do not add it merely because a simple managed or serverless deployment already handles the workload cleanly. A static site or a small request-driven API on a platform that already solves packing does not need you to pack it again.

Visual: pack once, run twice, store elsewhere

Picture three stages left to right: source files + Dockerfile (a folder and a recipe card) → one reusable image (a sealed box labeled research-app:v3) → the same container running in two places (a Mac mini and a VPS, each showing an identical running box). Off to the side, clearly separated: an external database cylinder and an object-storage bucket, with arrows showing both containers reading and writing to them. The separation is the teaching: containers travel, data stays.

Practical exercise: write CONTAINER-PLAN.md

Create a file called CONTAINER-PLAN.md for one service in your project (the web app or a worker — pick one). Include each of these lines:

• Service job: what this container does, in one sentence.
• Runtime: base language and version (e.g. Python 3.13, Node 22).
• Environment variables (names only): list the names it needs — never the values (e.g. DATABASE_URL, MODEL_API_KEY).
• Ports: which port it listens on inside the container, and which the outside world uses.
• External database/storage: which database and object storage it reads and writes — named explicitly as outside the container.
• Health check: the URL or command proving it is alive, and what healthy output looks like.
• Logs location: where its log lines go and how you read them.
• What must persist outside: the exact data that would be lost if the container were deleted today — and where that data actually lives instead.

Finish line: a reader can explain the difference between your Docker image, a running container of it, the VPS or Mac mini hosting it, and the database storing its durable data — using your plan as the example.

Verify: ask: "If I delete this container right now, what survives and where?" Every durable answer must point outside the container. Anything else is a redesign flag.

Common failure mode: baking secrets into the image or storing uploads inside the container. Secrets ride in environment settings at run time; files ride in object storage; facts ride in the database. The image carries code and runtime — nothing irreplaceable.

Check your understanding

1. Why does an app that works on your Mac fail on a fresh VPS? 2. What is a container — and how is it different from a virtual machine and from a server? 3. Define Dockerfile, image, and container, and put them in build order. 4. What three things does Docker give you on a VPS? What does it give you on a Mac mini? 5. Name five things Docker does not solve. 6. Why must no durable state live inside a disposable container — and where should it live instead? 7. When should you skip Docker even though you know how to use it?