How do I use Docker for local development without everything breaking?

MO Monica Torres MX 📗 Student 👁 81 ⚑ Report Programming

I've been trying to get Docker into my workflow for a month now, but every time I spin up the containers I get permission errors or ports that are already in use. I work on Windows with WSL2 and I have a Node project with PostgreSQL. Is there any way to do this without it being such a pain?

5 answers

★ Best answer

Permissions aren't as much of a headache as they seem at first, most people here are focused on ports and that's fine, but what nobody mentions is that on WSL2 you have to give Docker user permissions without throwing `sudo` at everything. You run `sudo usermod -aG docker $USER` just once, close and reopen the terminal, and that's it - after that Docker works without you having to fight with permissions every time you spin up a container. After that, setting things up with docker-compose becomes way smoother because you're not dealing with permission errors that get mixed up with port ones.

Port errors from already-in-use ports are the most common and annoying thing. First, check what's using the ports: on Windows/WSL2 run `netstat -ano | findstr :5432` (or whatever port you're using) to see which process has it. If it's another container that got stuck, kill the container with `docker rm -f container_name`. The permissions issue usually comes from WSL2 trying to mount volumes without the right permissions on Windows, so in your `docker-compose.yml` explicitly specify the ports and don't use complicated bind mounts at first; better to copy the code into the image or use named volumes that Docker handles better.

For your Node + PostgreSQL setup, the cleanest approach is a `docker-compose.yml` where you define the services without overcomplicating things. Map different ports if something's already using the standard ones (e.g. `5433:5432` for Postgres), make sure your Node can resolve the database container's hostname (use the service name in docker-compose, like `postgres:5432`), and restart everything clean: `docker-compose down -v` kills the containers and volumes, then `docker-compose up`. Watch out for named volumes vs bind mounts on WSL2; bind mounts sometimes act weird with permissions, so for local development just consider not mounting the code if you don't need to, or use named volumes that WSL2 handles better.

The part most people skip: check the logs. `docker-compose logs -f` shows you what's happening inside in real time; there you see if the app actually connects, if the database is ready, everything. And one thing that saves a ton of hours, especially on Windows: sometimes WSL2 and Docker have weird conflicts, so if it's still a mess, try Docker Desktop directly (not WSL2) or make sure your WSL2 version is up to date. Most people who ditch Docker on Windows do it because they don't update WSL2 or mix up their configs.

Before you start killing processes, make sure your `docker-compose.yml` has clear names for the services and that the ports in the file aren't hardcoded. What saves you here is using environment variables: instead of putting `5432:5432` directly, define a `.env` with `DB_PORT=5432` and in the compose you use `${DB_PORT}:5432`. That way when you need to change the port (because something's already using it) you only touch the config file in one place, you're not hunting through the code. Also, on WSL2 sometimes the containers get stuck; before you restart everything, try `docker system prune -a` to clean up the old stuff that's causing the mess.

The fastest way to avoid all that mess is to use environment variables in your `docker-compose.yml` instead of hardcoding ports, so you can change them without touching the file every time. In my case I had the same headache with PostgreSQL and Node running on WSL2, and what saved me was just creating a `.env` file with `DB_PORT=5432` and `NODE_PORT=3000`, then referencing them in the compose as `${DB_PORT}:5432` - if the port is taken I change one line in the `.env` and done, nothing breaks. I'd also recommend adding `restart: unless-stopped` to your services so they restart automatically if something fails, and about permissions on WSL2, run Docker directly from WSL instead of from PowerShell, because that way you avoid weird permission issues between Windows and Linux. One last thing: if you keep running into containers that won't die, `docker-compose down -v` cleans up absolutely everything including volumes, so you start fresh without ghosts.

Docker isn't complicated, it's just that WSL2 on Windows has its own pitfalls and nobody talks about them. What's gonna save you hours is simply stop thinking about ports and permissions as separate problems: most of the mess comes from containers not being able to talk to each other because you're using localhost instead of the service name inside the Docker network.

In your `docker-compose.yml`, in the Node-to-PostgreSQL connection string, don't put `localhost:5432`, use `postgres:5432` directly (or whatever you named the service). And in `.env` or container variables, set up the connection that way. That solves 80% of the permission drama you see: it's not that you don't have access, it's that you're pointing wrong. If you still want to expose the ports, map them in `ports: ["7654:5432"]` but inside the container always use the service name, not the host port.

Your answer

Log into answer.