Migrate from Docker Compose to NixOS on osModa
Docker Compose is the standard for defining multi-container applications, but containers add overhead, Dockerfiles are not truly reproducible, and rolling back a bad deployment means rebuilding images. NixOS provides the same declarative configuration with atomic rollbacks, genuinely reproducible builds, and no container runtime overhead -- on a dedicated osModa server from $14.99/mo.
TL;DR
- • Docker Compose defines containerized services; NixOS declares the entire system
- • NixOS builds are content-addressed and truly reproducible; Docker builds are not
- • NixOS atomic rollback reverts the entire system; Docker can only roll back individual containers
- • No Docker daemon overhead -- processes run natively on the host
- • You can still use Docker on osModa if you prefer an incremental migration
Step-by-Step Migration from Docker Compose
Migrating from Docker Compose to NixOS requires more conceptual work than migrating from a PaaS, because you are changing how services are defined and managed rather than just deploying to a different platform. Plan for 1-3 hours depending on the number of services in your docker-compose.yml.
Step 1: Audit Your docker-compose.yml
Review every service in your docker-compose.yml. For each service, note: the base image (e.g., python:3.11, node:20), installed packages (from the Dockerfile), environment variables, ports, volumes, and dependency relationships between services. This inventory tells you exactly what needs to be translated to NixOS configuration.
Step 2: Spawn an osModa Server
Choose a plan based on the combined resource requirements of all your Docker services. If your docker-compose.yml runs 3 containers that collectively need 2 CPU and 3 GB RAM, the Solo plan ($14.99/mo, 2 CPU, 4 GB RAM) is sufficient. Spawn via the dashboard or API. Provisioning takes 5-10 minutes.
Step 3: Translate Dockerfiles to NixOS Packages
Each Dockerfile's package installations map to NixOS package declarations. If your Dockerfile runs apt-get install python3 postgresql-client redis-tools, the NixOS equivalent is declaring environment.systemPackages = [ python3 postgresql redis ] in your configuration.nix. Every package in the Nix package repository (over 100,000 packages) is available. SSH into the server and update the NixOS configuration to include your required packages.
Step 4: Translate docker-compose.yml Services to NixOS Services
Each service in your docker-compose.yml becomes either a systemd service or a process managed by osmoda-watch. A Compose service like web: build: . command: python app.py ports: ["8080:8080"] becomes: install python3, copy your application code to the server, and run python app.py as a monitored process. For databases like PostgreSQL, NixOS has built-in service modules that configure the database declaratively.
Step 5: Translate Networking
Docker Compose creates a bridge network where services reference each other by service name. On NixOS, all services run on the same host, so inter-service communication uses localhost. Replace postgres://db:5432 with postgres://localhost:5432. For multi-server setups (replacing Docker Swarm), osmoda-mesh provides encrypted networking between osModa servers.
Step 6: Apply and Test
Apply your NixOS configuration with nixos-rebuild switch. NixOS applies the new configuration atomically -- all services start in the new state, or the system stays on the previous generation. If something breaks, roll back instantly with nixos-rebuild switch --rollback. Test all services and verify inter-service communication.
Before and After: Docker Compose vs NixOS
| Aspect | Docker Compose (Before) | NixOS on osModa (After) |
|---|---|---|
| Config Format | docker-compose.yml + Dockerfile(s) | configuration.nix (entire system) |
| Reproducibility | Partial -- apt-get varies by date | Yes -- content-addressed, deterministic |
| Rollback | Per-container image rollback | Yes -- atomic whole-system rollback |
| Runtime Overhead | Docker daemon + container runtime | None -- native processes |
| Networking | Docker bridge network (service names) | localhost + osmoda-mesh for multi-server |
| Storage | Docker volumes (managed by Docker) | Filesystem directories (standard Linux) |
| Scope | Application containers only | Entire OS + applications |
| Process Supervision | Docker restart policies | Yes -- osmoda-watch + systemd |
Why NixOS Over Docker
Truly Reproducible Builds
Docker images are often marketed as reproducible, but this is only partially true. A Dockerfile that runs apt-get update && apt-get install -y python3 produces different results depending on when you build it because APT repository contents change daily. NixOS builds are content-addressed: every package is identified by a cryptographic hash of all its build inputs. The same NixOS configuration always produces the identical system, regardless of when or where it is built.
Atomic Rollbacks
Docker can roll back a single container to a previous image, but it cannot atomically roll back the entire system. If you update your app container and your database schema simultaneously and something breaks, rolling back the app container does not roll back the schema change. NixOS rolls back the entire system state atomically via SafeSwitch. One command reverts everything to the previous known-good generation -- every package, every configuration file, every service.
No Container Overhead
Docker adds runtime overhead: the Docker daemon process, container networking (iptables rules, bridge interfaces), storage driver overhead for layered filesystems, and the namespace/cgroup isolation layer. For AI agents running compute-intensive workloads, this overhead matters. On NixOS, your applications run as native processes with direct filesystem access and native networking.
What Requires Manual Work
Docker has a massive ecosystem of pre-built images on Docker Hub. If your workflow relies heavily on pulling third-party images, you will need to find equivalent NixOS packages or build from source. The NixOS package repository has over 100,000 packages, but some niche software may require writing a Nix derivation. NixOS configuration syntax (the Nix language) has a learning curve, especially for teams already fluent in Dockerfiles. And Docker's container isolation provides a security boundary that NixOS processes running on the same host do not have (though NixOS offers systemd sandboxing and other isolation mechanisms).
Explore More Migration Guides
- Migrate from Kubernetes -- 22+ concepts to SSH + NixOS
- Migrate from Heroku -- dynos to dedicated servers
- NixOS Atomic Deployments -- deep dive on rollback mechanics
- NixOS vs Docker for AI -- detailed comparison blog post
- All migration guides -- complete list of platform migration guides
Frequently Asked Questions
Do I have to stop using Docker on osModa?
No. NixOS supports Docker, and you can run your existing Docker Compose setup on an osModa server if you prefer. However, the recommended approach is to translate your Docker services to native NixOS services, which eliminates container overhead, provides atomic rollbacks for your entire system state, and gives you truly reproducible builds. You can migrate incrementally -- run some services in Docker and others natively while you transition.
How do I translate a Dockerfile to NixOS?
A Dockerfile defines a series of steps to build a container image: base image, package installation, file copying, and entrypoint command. In NixOS, this translates to: declaring packages in your system configuration (replacing apt-get/apk install), copying your application files to the server, and defining a systemd service or directly running your application. The key difference is that NixOS packages are declared, not imperatively installed, so builds are reproducible by default.
What replaces docker-compose.yml on NixOS?
NixOS's configuration.nix (and any imported modules) serves a similar purpose to docker-compose.yml. It declares all services that should run on the system, their configuration, environment variables, and dependencies. The difference is that NixOS configuration covers the entire OS -- not just containerized services. Every service, package, user, and system setting is declared in one place, and changes are applied atomically.
What about Docker volumes for persistent data?
Docker volumes map to regular filesystem directories on NixOS. Since osModa gives you a full server with persistent storage (40-320 GB depending on plan), your application data lives directly on the filesystem. There is no volume driver abstraction, no volume management commands, and no risk of orphaned volumes. Data persists across reboots and system updates because NixOS atomic rollbacks do not affect user data directories.
How do I handle multi-container networking?
Docker Compose creates a network where containers communicate by service name. On NixOS, services communicate via localhost since they all run on the same machine. Your web server connects to PostgreSQL at localhost:5432 instead of postgres:5432. For multi-server architectures (replacing Docker Swarm or distributed Compose), osmoda-mesh provides encrypted peer-to-peer networking between osModa servers.
Are NixOS builds really more reproducible than Docker?
Yes. Docker builds are only reproducible if every layer is deterministic, which is often not the case. Commands like 'apt-get update && apt-get install' produce different results depending on when they run because package repositories change. NixOS builds are content-addressed: every package is identified by a cryptographic hash of its inputs. The same NixOS configuration always produces the same system, regardless of when or where you build it.
Reproducible. Atomic. No Container Overhead.
Replace Docker Compose with NixOS declarative configuration on a dedicated server. Self-healing, audit logging, and atomic rollbacks included. From $14.99/mo.
Explore More
Last updated: March 2026