Your auroralibros/aurora-api:1.1.0 image is published and it is spotless: unprivileged user, OCI metadata, healthcheck and a clean 0.3-second shutdown. And it still returns ECONNREFUSED on /books, exactly as the previous lesson warned you. This entire module exists to fix that, and it starts where it has to start: really understanding the command you have been using since lesson 01-06 without ever looking at it closely. docker run is not one command, it is two: it creates a container and it starts it. And it accepts more than a hundred options, of which about fifteen get used in day-to-day work. In this lesson you are going to see what run does under the hood, you are going to learn those fifteen options grouped into families, you are going to override an image's CMD and ENTRYPOINT from the command line, and you are finally going to bring up aurora-db and aurora-cache as real containers. By the end you will have three live containers... and the API still will not work. That failure, with its error message changed, is the clue that kicks off the rest of the module.

1. What docker run really does: create + start
2. Anatomy of the command and the order of the arguments
3. Identity family: --name and --hostname
4. Execution family: -d, -it, --rm, -w, -u, --entrypoint
5. Network and ports family: the bare minimum to work
6. Configuration family: -e and --env-file
7. Data family: -v in its minimal form
8. Overriding CMD and ENTRYPOINT from the command line
9. Foreground, background and how to detach
10. docker attach versus docker exec
11. Hands-on: the Aurora Libros database and cache

docker run is a shortcut. Underneath it performs two distinct operations that you can invoke separately:

Docker prints the container's full ID (64 hexadecimal characters) and hands control back to you. Notice what has happened and what has not:

The container exists, it has its writable layer reserved and all its configuration stored (ports, variables, command), but the state is Created and the PORTS column is empty: no process is running and port 8080 is not listening on your machine. Check it:

Now start it:

docker start prints the name of the container it started. And now, yes:

This separation is not an academic detail: it explains the division of responsibilities you are going to rely on throughout the module.

The practical consequence, worth burning into your memory right now: you cannot add a port or an environment variable to a container that already exists. If you got it wrong, you delete it and create it again. That is exactly why in module 4 you will end up writing that configuration into a file instead of on the command line.

Clean up the demonstration:

The complete flow, now that you know the pieces from lesson 01-03:

There is a single golden rule, and it causes half of all beginner errors:

Everything before the image is a Docker option. Everything after the image is the command that runs inside the container.

Watch it fail:

Docker did not read -e as one of its own options: because it came after alpine:3.20, it tried to run a program called -e inside the container. The correct version:

Here --rm and -e MESSAGE=hello are Docker options (they go before the image) and sh -c 'echo $MESSAGE' is the command inside the container (it goes after). We need sh -c because expanding $MESSAGE is a shell's job, and without it Docker would pass the literal string.

An overview of the families you will meet in the sections that follow:

Without --name, Docker invents a two-word name (nostalgic_hopper, elegant_bardeen) and forces you to copy IDs around. With a name, every subsequent command becomes readable and scriptable:

The rules for names:

That last point is the key to the whole module, and it is why the Aurora Libros names (aurora-db, aurora-cache, aurora-api, aurora-web) are not decorative: very soon they will be real hostnames.

The most common mistake with --name:

Careful: the conflict happens even if the previous container is stopped. An Exited container still occupies its name. You resolve it with docker rm aurora-cache (or docker rm -f if it is running).

It changes the name the container sees for itself inside its own UTS namespace:

Without --hostname, the hostname is the container's short ID:

--name and --hostname are different things: --name is how you call it from outside (and how other containers call it over DNS); --hostname is what the container calls itself. It gets little use, but it shows up in application logs and in database clusters.

It returns the ID and leaves your terminal free. Without -d, the terminal stays busy showing the process's output and Ctrl+C stops it.

Try dropping one of the two letters to understand what each one contributes:

A practical rule: -it for people, -d for services, nothing for one-shot commands. And never -it in an automated script or in CI: with no real terminal, -t triggers the input device is not a TTY.

The container runs, prints and disappears: it does not linger in docker ps -a and it takes up no writable layer. It is the option that stops you accumulating dozens of dead containers.

Two important warnings:

• --rm is incompatible with debugging: if the container fails, it is deleted along with its logs and its inspect. When something goes wrong, drop the --rm so you can investigate (lesson 03-04).
• --rm also deletes the associated anonymous volumes. With named volumes nothing happens, but it is a detail we come back to in lesson 03-06.

• -w /tmp overrides the WORKDIR /app you set in the Dockerfile.
• -u 1000:1000 forces a specific UID:GID even if that user does not exist inside the image (which is why id shows the numbers without names).
• -u root cancels the USER node in your image. It is extremely handy for debugging (installing a tool inside an unprivileged container), and at the same time a reminder that USER is defense in depth, not an impassable barrier: whoever can launch containers can choose the user.

You already used it in lesson 02-04, and here it gets its proper place:

Without --entrypoint, your image has a fixed ENTRYPOINT ["node"] and anything you wrote after the image would be an argument to node. With --entrypoint sh you get in and look around. It is the service door of every well-built image.

Only the essentials here; the full explanation arrives in lesson 03-05.

-p HOST:CONTAINER means "anything arriving at port 8080 on my machine, forward it to port 80 of this container". The order is never reversed: host first, container second.

Check -P with your own image, which declares EXPOSE 3000:

Docker picked 32768 from the ephemeral range. docker port is the command that answers "which host port did this end up on?".

Two ideas worth fixing right away, even though they are developed in 03-05:

• EXPOSE in the Dockerfile and --expose in run open nothing: they are documentation consumed by -P and other tools.
• Publishing a port is what lets you, from the host, reach the container. For two containers to talk to each other, nothing needs to be published. That distinction is the one that is about to solve the API's mystery.

Clean up:

Your server.js does not have a single hardcoded value: it reads PORT, DB_HOST, DB_USER, DB_PASSWORD, DB_NAME and REDIS_HOST from the environment. That decision from lesson 01-07 is what lets the same image serve your laptop, testing and production.

The second form is very practical for keeping secrets off the command line, where they would end up in the shell history.

Variables defined with -e override those from the Dockerfile's ENV. Check it with your image, which ships ENV PORT=3000:

And look at the whole precedence ladder again:

Once you pass three variables, the command line becomes unreadable. Create ~/aurora-libros/aurora.env:

And use it:

The format rules are strict and different from a shell script's. This is a spot where a lot of time gets lost:

And a security rule you already know from module 2, now with its concrete consequence:

The environment file contains a password: it goes neither into the Git repository nor into the build context. The image stays free of secrets —as it should— and the configuration travels outside it, injected at startup. You can combine both options: --env-file for the bulk and -e for whatever you want to override on the spot, because -e beats --env-file regardless of the order you write them in.

You used it in lesson 01-06 to serve your index.html with Nginx:

The minimal syntax is -v SOURCE:DESTINATION[:options], with the host path always absolute and :ro to mount read-only. That is enough until lesson 03-06, where you will see the three types of mount, managed volumes and why the book catalog you are about to create will vanish if you do nothing about it. For now, hold on to the idea from lesson 01-05: everything a container writes outside a mount lives in its writable layer and dies with it.

We pick up the table from lesson 02-04, now from the execution side. Your image declares:

The effective command is the concatenation ENTRYPOINT + CMD → node server.js. And from docker run you can touch each half separately:

Check it:

Two subtleties that catch people out:

• Overriding the ENTRYPOINT discards the image's CMD. In row 4 of the table, CMD ["server.js"] disappears: if you did not want sh to receive server.js as an argument, you have nothing to do, it is already gone.
• --entrypoint "" (empty string) is the way to leave the image with no fixed executable, so that whatever you write after the image is the complete command. It is the trick that saves the day with images whose entrypoint is a complicated script.

When you start without -d, your terminal stays hooked to the input and output of PID 1:

And there it stays. If you press Ctrl+C, you send SIGINT to the process and the container stops. That is rarely what you want with a service.

The alternative, if you started with -it, is to detach without killing it using the sequence Ctrl+P followed by Ctrl+Q:

Still alive. Three conditions for the sequence to work, and their absence explains 90% of the "it doesn't work for me" cases:

1. The container must have been started with -t (it needs the pseudo-terminal).
2. It must be hooked to stdin, that is, with -i.
3. The sequence is pressed inside the session, not in another terminal.

If you need Ctrl+P for something else (in bash it recalls the previous command), change it:

Now the combination is Ctrl+E followed by e. You can make it permanent in ~/.docker/config.json:

A summary of the three ways to start:

Clean up:

A container in the background can be "looked at again" in two radically different ways:

docker attach connects you to the input and output of the PID 1 process that already exists. It launches nothing new. And that is where its danger lies:

You just stopped Redis. Ctrl+C during an attach goes straight to PID 1. To leave without killing it you have to use Ctrl+P Ctrl+Q, or connect in safe mode from the start:

With --sig-proxy=false, Ctrl+C gives you the prompt back without sending the signal to the container.

docker exec, in contrast, launches a new process inside the container:

That redis-cli has nothing to do with PID 1: it is a second process that shares the container's namespaces and that can finish without affecting the service.

The practical rule: to watch output use docker logs, and to get in use docker exec. Both are studied in depth in lesson 03-04. docker attach is reserved for processes that genuinely wait for your keyboard input.

The moment has arrived. Until now the API started on its own and failed because there was neither PostgreSQL nor Redis. Let's put them in place.

Let's go over each line, because each one has its reason:

Check that it is alive:

pg_isready is PostgreSQL's official tool for asking "are you accepting connections?". We run it inside the container with docker exec, with no need to have PostgreSQL installed on the host. That detail —using the tools that already ship in the image— is one of Docker's most underrated conveniences.

And check that the database exists, even if it is still empty:

Correct: the aurora_books database is created, but there are no tables. db/init.sql still needs to run, and that will happen automatically and elegantly in lesson 03-06, when you mount that file inside the container.

Redis needs no variables: it starts with its default configuration.

Redis works. Two live containers.

Docker accepted the command without complaining. But:

The container did not even stay running. It started and died with exit code 1. Let's see why:

Look carefully at the message, because it has changed since module 2 and that change is a first-rate clue:

And here is the paradox that gives the rest of the module its purpose: aurora-db and aurora-cache are running right now, on the same machine, publishing their ports. You can verify it from the host:

They are alive, they are published, and even so aurora-api cannot find them. Why?

The short answer: because they do not share a network. Each container has its own network stack, and on Docker's default network there is no name resolution between containers. The long answer, with the complete solution and the curl that returns the eight books, is lesson 03-05. For now, leave the question open and delete nothing: these two containers will keep you company throughout the module.

We only delete the API (it is stopped and it is useless). aurora-db and aurora-cache stay.

• Putting options after the image. docker run alpine -e VAR=1 sh tries to run a program called -e. Options go before the image, always.
• Expecting to add a port or a variable to an existing container. You cannot: they are frozen in the create phase. The solution is docker rm and create it again. When that starts to wear you down, you will be ready for module 4.
• Using --rm while debugging. If the container fails and gets deleted, you are left with no logs and no inspect. During an investigation, drop the --rm.
• -p 5432:5432 on a database. It publishes PostgreSQL on all interfaces, including the café's Wi-Fi. Use -p 127.0.0.1:5432:5432, or simply do not publish it: containers do not need published ports to talk to each other.
• Reversing the order in -p. -p 80:8080 with Nginx does not work and the error is confusing, because Docker happily publishes host port 80 towards an 8080 where nobody is listening. Host first, container second.
• -t in scripts and CI. the input device is not a TTY. In automation use -i or nothing, never -t.
• Quotes in an --env-file. DB_PASSWORD="aurora_secret" stores the password with the quotes included and causes a baffling password authentication failed. No quotes.
• Tip: always use --name. An unnamed container is a container you will be hunting for by ID ten minutes from now in a twenty-line docker ps -a.
• Tip: write long docker run commands across several lines with a trailing \, and keep them in a notes file. You are going to repeat them many times, and in lesson 03-07 you will see how much they have grown.

Without using docker run at any point, create an nginx:alpine container called lifecycle-exercise published on port 8090 and with the variable ENVIRONMENT=tests. Before starting it, answer with commands: what state is it in? Does port 8090 respond? Does it show up in docker ps? Then start it, check the three things again, and try to add a second port (8091) without deleting it. Explain what happens and why.

Using only the auroralibros/aurora-api:1.1.0 image and without rebuilding it, produce these five outputs, writing the exact command in each case:

1. The installed Node version.
2. The contents of /app/package.json.
3. An interactive shell inside the container.
4. The result of console.log(process.env.DB_HOST) with DB_HOST set to aurora-db.
5. The file listing of /app by running ls directly, with no node and no sh involved.

Create two environment files, aurora-dev.env and aurora-test.env, that differ in PORT (3000 and 3100), DB_NAME (aurora_books and aurora_books_test) and REDIS_HOST. Start two API containers with the same command except for the --env-file and the --name, verify with printenv that each one has its own configuration, and then start a third that uses aurora-dev.env but with PORT=3200 overridden from the command line. Answer: how many different images did you need? And which line of your .gitignore stops this ending up in the repository?

Solution to exercise 1

State before starting:

The three answers: state created, the port does not respond (code 000, connection refused) and it does not appear in docker ps (the third command's output is empty), because docker ps without -a only lists running containers. The configuration is stored, but there is no process and no network rule.

Now it works: it appears in docker ps, the port returns 200 and the variable you defined in the create phase is present.

The attempt to add a port:

There is no way to do it. docker update only modifies resources (memory, CPU, restart policy — lesson 03-07), never ports, variables or mounts: those are frozen when the container is created because they involve network namespaces and forwarding rules that are built at startup. The only way out is to recreate it:

This rigidity is precisely the argument in favor of declaring configuration in a versioned file instead of on the command line, which is what Docker Compose does in module 4.

Solution to exercise 2

Case 4 is the most instructive of the exercise: there are two -e flags in the same command and they mean different things. The first is before the image, so it is Docker's --env option; the second is after, so it is an argument Docker hands over untouched to ENTRYPOINT ["node"], and there -e is Node's option for evaluating code. The rule from section 2 explains it without ambiguity.

Case 5 shows the difference between --entrypoint ls and --entrypoint "". With --entrypoint ls you would still have to write the arguments after the image, but with --entrypoint "" the line reads naturally: the image stops imposing an executable and everything that follows is the complete command.

Solution to exercise 3

Verification with printenv, without starting the API (which would fail for reasons you already know):

The third one, with a one-off override:

PORT is 3200 (the -e won) and DB_NAME keeps the file's value. -e always takes precedence over --env-file, regardless of the order you write them in on the command line: try swapping them around and you will get the same result.

The two final answers:

• A single image. auroralibros/aurora-api:1.1.0 served three different configurations without being rebuilt even once. This is the build once, deploy everywhere principle you saw in lesson 02-06: what changes between environments is the injected configuration, never the image.
• The .gitignore line is *.env (or aurora-*.env). These files contain DB_PASSWORD=aurora_secret; they do not go into the repository, and not into the .dockerignore either, so that they never end up in the build context nor, by accident, inside an image layer.

docker run has stopped being a magic formula. You know it is two operations, create and start, and you have proved it by running them separately: the create phase reserves the writable layer and freezes the configuration —which is why you cannot add a port or a variable to an existing container— and the start phase sets up namespaces, cgroups and network rules and launches PID 1. You know the golden rule about argument order, which separates Docker's options from the command inside, and you have the five families of options sorted out: identity, execution, network, configuration and data.

You handle -d for services, -it for people and --rm for throwaway commands, knowing that --rm becomes your enemy the moment something fails. You know how to override an image's CMD half and ENTRYPOINT half separately, including the complete cancellation with --entrypoint "". You know how to detach from a session with Ctrl+P Ctrl+Q without killing the process, and why docker attach is a sharp tool that can take a service down with one distracted Ctrl+C, as opposed to docker exec, which launches an independent process. And you know how to keep configuration outside the image with --env-file, with its strict format rules and its password that never enters Git or the build context.

Above all, the platform has started to move: aurora-db and aurora-cache are running right now on your machine, with PostgreSQL 16 accepting connections and Redis answering PONG. And aurora-api no longer gives ECONNREFUSED: it gives getaddrinfo ENOTFOUND aurora-db, a different error that says something very specific —the name does not even resolve— and that points straight at the solution. On top of that, the container did not end up unhealthy: it died in two seconds with exit code 1.

And that raises the question the course continues with: why do some containers keep running indefinitely while others die instantly? In the next lesson, Container Lifecycle, you are going to see the seven states a container passes through and the transitions between them, the rule that a container lives exactly as long as its PID 1 process lives, the difference between an orderly stop with SIGTERM and a SIGKILL ten seconds later, and the table of exit codes —that 1, and also 125, 137 and 143— that turns a cryptic number into a diagnosis. And you will teach server.js to shut down cleanly, closing the PostgreSQL pool and the Redis client before it goes.