Invisible Node.js Setup with Docker

Edit:

After using this setup for a while, I realized that it's not worth the effort. I have starting using devcontainers in VS Code for my projects. It does everything described here and more. I still use this setup for quick one-off commands, running self-hosted services, or when I need to test the build output with a different version of Node.js, without having to set up a devcontainer.

Edit: 2024-06-24

I am looking into using nix for managing my development environment. Docker is a full-fledged containerization tool and sometimes too restrictive for my use case. Updating devcontainer configs and rebuilding the container is a slow process. Developing GUI applications inside a container, accessing os-specific features like keychain, accessing devices are very difficult to setup. devcontainers also do not support user-specific configurations on top of the base environment required for the project.

nix-shell seems to be a much better solution, since it is geared towards development environments, and just providing the tools and binaries you need for the project. Everything else will be provided by the host system.

Last year I replaced my system package manager with docker. It was a game-changer, but one challenge stood out: setting up tools to feel like native installations.

This was my initial setup:

docker run -it --rm \
  -v "${PWD}:/workspace" \
  node:16-alpine

Let's break it down

-it flag is for interactive mode with a pseudo terminal. This is runs the container in the foreground and allows me to interact with it.
--rm flag is to remove the container after it exits. This cleans up the container after exiting, saving RAM.
-v "${PWD}:/workspace" mounts the current directory to /workspace inside the container. This allows me to access the files from the current directory inside the container.
node:16-alpine is the image I want to run. This is the official Node.js image based on Alpine Linux.
By default, the container runs the node command. Adding sh or npm at the end will run the shell or npm respectively inside the container.

The problems

Verbosity. I need to type and remember this command every time I want to run node or npm.
With the --rm flag, I lose access to the container after it exits. I can't access the repl history or any files created inside the container.
Without the --rm flag, I have to remember to stop the container manually to free up memory.
Cold start. Every time I run this command, a new container is created.
I have to relearn the command syntax. I can't use my muscle memory from regular installations.
Barebones shell. I can use the shell inside the container, but I would much prefer my pretty prompt and completions.

Quick wins

Start the container in the working directory. I can use the --workdir or -w flag for this.
```
-w "/workspace"
```
When creating files inside the workspace from the container , I need them to have the correct owner so they can be accessed from the host. I can set the user using the -u or --user flag.The node user is predefined in the image with uid 1000 and gid 1000. This should work fine for most linux systems.
```
-u "node"
```
I need to preserve my repl history. I can simply mount the history file that would have been created during a regular installation.
```
-v "${HOME}/.node_repl_history:/home/node/.node_repl_history"
```
I might want to publish a package on npm or download private packages. Similar to the repl history, I can mount the .npmrc file.
```
-v "${HOME}/.npmrc:/home/node/.npmrc"
```
To download packages or make fetch calls from the repl, I need to setup a network. For simplicity, I can just use the host network.
```
--network host
```

The final command looks like this:

docker run -it --rm \
  -u "node" \
  -v "${PWD}:/workspace" \
  -v "${HOME}/.npmrc:/home/node/.npmrc" \
  -v "${HOME}/.node_repl_history:/home/node/.node_repl_history" \
  -w "/workspace" \
  --network host \
  node:16-alpine

Next steps

Easy peasy. Now I can run node and npm commands without any issues. But I still haven't solved the cold start problem. I need to keep a container running in the background to avoid creating a new container every time I want to run a command.

We can start a container in the background using the -d flag. This is for "Detached" mode. We can later attach back to it or execute commands inside it. We also need to make sure the container doesn't exit immediately. We can run tail -f /dev/null to keep the container running in the background doing nothing.
```
docker run -it -d \
  ...
  --entrypoint tail \
  node:16-alpine -f /dev/null
```
Our container will be created with a random name. We can give it a name to refer to it later. This is useful when we want to execute commands inside the container.
```
--name node
```

Now we can execute commands inside the container. We can create aliases for common commands.

alias node='docker exec -it node node' # run the node repl
alias npm='docker exec -it node npm' # npm install, npm publish, etc
alias npx='docker exec -it node npx' # curl bashing with extra steps
alias node:shell='docker exec -it node sh' # useful for debugging

It will be nice to know what directory is mounted in the container instead of the generic /workspace. We can use the basename command to get the name of the current directory.
```
  -w "/workspace/$(basename ${PWD})" \
```

And finally, adding alias for the start command. We can also add aliases for stopping and restarting the container.

alias node:start='docker run -it -d \
  -u "node" \
  -v "${PWD}:/workspace/$(basename ${PWD})" \
  -v "${HOME}/.npmrc:/home/node/.npmrc" \
  -v "${HOME}/.node_repl_history:/home/node/.node_repl_history" \
  -w "/workspace/$(basename ${PWD})" \
  --name node \
  --network host \
  --entrypoint tail \
  node:16-alpine -f /dev/null'
alias node:stop='docker stop node; docker rm node; true'
alias node:restart='node:stop; node:start'

Limitations

You can only execute commands from the project's root. If you cd in the host shell, the workdir inside the background container will still be on the root path.
You can only have a single instance of the background container running. You won't be able to run multiple projects simultaneously.
VS Code and other editors / LSP will not work, unless you install and run your editor inside the container.

Enhancements:

When creating new background containers, I can use the project name as a suffix to the container name. This will allow me to run multiple projects simultaneously. Or maybe I can store the stdout from the docker-run, which contains the container id, of the new container in a $NODE_CONTAINER variable.
Since aliases are only available in interactive shells, I cannot use them in scripts. I can create scripts in /usr/local/bin instead of defining aliases. You can check these and many more docker related scripts in my dotfiles.

P.S. A little horror story: While trying to sell Docker to a friend, I completely forgot I had a container running in the background with a different project directory mounted. I ended up accidentally rm -rfing my project while trying to convince him that Docker keeps you safe from this exact scenario. 😭