Docker on a VPS: Installation and First Container

Docker on a VPS: installation and your first container

In the previous series, we automated the code delivery process itself: push to a branch, and within minutes the change is live on the server with no human involved. But the "push → SSH deploy → restart the service" scheme only cures one symptom. The second, no less painful one, stays exactly where it was: dependencies on the server still have to be installed by hand, and they conflict between projects living on the same VPS.

A classic situation: one project is written for Node.js 18 and depends on a specific major version of its packages, another is newer, already on Node.js 20. Both need to deploy to the same server. Without Docker, that's either two system-wide Node.js installs fighting each other through nvm and PATH variables, or a compromise where one of the projects runs on a version it was never tested against. The same thing repeats with PHP, Python, library versions, system packages — any shared dependency on the host eventually becomes a point of conflict.

Docker solves this at the architecture level, not through agreement. Every application gets its own isolated environment with its own dependencies, and that environment is described in code, not in the administrator's head. The same image you built and tested locally runs on the server bit-for-bit identical. And rolling back to a previous version isn't "remember which files to overwrite" — it's one line: docker run with the old image tag.

2. Key Docker concepts

Before installing anything on a server, it's worth getting familiar with five terms, without which no Docker command will make sense.

2.1 Image — an immutable template

An image is a read-only template a container is launched from: a filesystem, installed dependencies, environment variables, a default startup command. An image never changes on its own — node:20-alpine, nginx:latest, or your own my-app:1.0 stay the exact same bytes until you explicitly build a new image.

2.2 Container — a running instance

A container is a process launched from an image, with its own filesystem on top of the image's layers, its own network namespace, and its own PID namespace. You can launch as many containers as you like from a single image at once, and each will be isolated from the others, even if they come from the exact same image.

2.3 The layer system and build cache

Every instruction in a Dockerfile creates a separate layer, and layers get cached. If package.json hasn't changed since the last build, the npm install layer is pulled from cache without re-running — this is exactly the property that makes repeated CI builds many times faster than the first one.

2.4 Image registries

Docker Hub is the default public registry: docker pull nginx with no extra configuration downloads the official image from there. But it's not the only option.

2.5 Docker Engine vs Docker Desktop

Docker Desktop is a graphical wrapper for local development on Mac and Windows, with its own virtual machine under the hood. On a VPS it isn't needed and doesn't even get installed: the server gets only Docker Engine — the daemon (dockerd) and the CLI, with no graphical layer whatsoever. It's the Engine we install in the next section.

3. Installing Docker on a VPS

3.1 Why not apt install docker.io

The simplest path turns out to be a trap. The docker.io package from Ubuntu's or Debian's standard repository is a version frozen at the distribution's release date — typically 20.x at a time when the current line is already 26.x and above. The difference isn't just a version number: older builds are missing security fixes and a chunk of modern BuildKit features.

3.2 The official way — the Docker Inc. repository

The fastest reliable option is the official install script:

curl -fsSL https://get.docker.com | sh

The script detects the distribution on its own, adds the official Docker repository, and installs the current Community Edition together with containerd and the CLI plugins (Compose, Buildx). For production servers where piping a script from the internet isn't a preferred option for security reasons, the same repository can be added manually following the official documentation for your specific distribution.

3.3 Running without sudo

By default, only root has access to the Docker daemon, and every command needs sudo. To work as a regular user:

sudo usermod -aG docker $USER
newgrp docker

Instead of newgrp docker you can simply log back in — the group change applies on the next login.

3.4 Autostart after a reboot

The official install script already enables autostart, but it's worth confirming explicitly:

sudo systemctl enable docker

3.5 Verifying the installation

docker --version
docker info
docker run hello-world

The last command is the best quick test: if Docker can pull a tiny image and print a greeting, the daemon is running, permissions are set up correctly, and the network for pull requests is reachable.

4. First commands: hands-on with nginx

Theory only clicks after a few commands in the terminal. Let's walk through a container's lifecycle using nginx as an example.

4.1 Pulling an image

docker pull nginx:alpine

The tag is specified explicitly instead of latest — this matters for reproducibility: latest today and latest in a month can be different images, and a server hit by a stray untagged docker pull can one day get an unexpected major version.

4.2 Starting a container

docker run -d -p 80:80 --name my-nginx nginx:alpine

4.3 Viewing running containers

docker ps
docker ps -a

docker ps shows only running containers, -a adds stopped ones too — useful for finding a container that exited with an error right after startup.

4.4 Logs

docker logs my-nginx
docker logs -f my-nginx

-f (follow) works just like tail -f: convenient to keep open while diagnosing a problem in real time.

4.5 A shell inside the container

docker exec -it my-nginx sh

Opens an interactive shell inside an already-running container — check a config, inspect the network, look at files, without stopping the service.

4.6 Stopping and removing

docker stop my-nginx
docker rm my-nginx

stop sends a termination signal to the process inside the container, rm deletes the container itself along with its filesystem. The image it was created from stays on disk.

4.7 Managing images on disk

docker images
docker image prune

docker images lists downloaded images with their size, image prune clears out dangling images — the ones left untagged after a rebuild reused the same name.

5. Your first Dockerfile: a custom image

5.1 .dockerignore — the first file, not the Dockerfile

Before writing a Dockerfile, it's worth creating a .dockerignore: node_modules, .env, .git, *.log shouldn't end up inside the image. Without this file, the build context (everything sent to the daemon) balloons, and secrets from .env can accidentally end up baked into an image layer forever.

5.2 Dockerfile structure

The order of instructions matters — it's exactly what determines what gets cached and what gets rebuilt every single time:

FROM node:20-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production
COPY . .
CMD ["node", "server.js"]

5.3 Why package*.json is copied separately

If you copy the whole codebase with a single COPY . . before installing dependencies, any change in the code invalidates the npm ci layer's cache, and dependencies get reinstalled from scratch on every build. Splitting this into two steps means the npm ci layer is pulled from cache until package.json or package-lock.json themselves actually change.

5.4 Alpine or the full image

5.5 CMD or ENTRYPOINT

5.6 Building the image

docker build -t my-app:1.0 .

The same image can get a second tag without a rebuild — for example, docker build -t my-app:latest . in the same context creates another tag on the exact same layers.

5.7 Running your custom image

docker run -d -p 3000:3000 --name my-app my-app:1.0

6. Volumes: data outside the container

6.1 Why data disappears

A container's filesystem is ephemeral by design: docker rm deletes everything written inside it during its lifetime. For a stateless app that's not a problem, but for a database or any service holding state, it means data loss on every container update.

6.2 Bind mount

docker run -v /var/log/myapp:/app/logs my-app:1.0

A directory from the host is mounted directly inside the container, and changes show up on both sides in real time. Handy for configs you need to edit from outside, and for logs a separate monitoring system on the host reads afterward.

6.3 Named volume

docker volume create pgdata
docker run -v pgdata:/var/lib/postgresql/data postgres:16-alpine

A named volume is managed by Docker itself and physically lives under /var/lib/docker/volumes/. For databases this is usually the better choice over a bind mount: Docker handles the paths and permissions on its own, and a backup can be taken through a helper container with --volumes-from, without worrying about the host's exact directory structure.

6.4 Managing volumes

docker volume ls
docker volume inspect pgdata
docker volume prune

prune removes volumes not used by any container — useful, but worth checking the list before running it: data deleted this way is gone for good.

7. Conclusion

Over the course of this article, we went from installing Docker Engine on a clean VPS to a custom-built image with data that survives a container restart. That's already enough to run a single application isolated from the rest of the system, without worrying about Node.js or Python version conflicts with a neighboring project.

An inconvenience that becomes obvious after your first few containers: every service is its own long docker run line with ports, environment variables, and volumes — easy to mix up or forget to recreate after a server update. Once an application isn't a single container but several — the app itself, a database, a cache — managing that set with individual commands gets hard and error-prone.

That's exactly the problem Docker Compose solves: the whole stack is described once in a docker-compose.yml file and comes up with a single command.

Frequently Asked Questions