Docker Deployment

This guide explains how to run Mercury as a web application using Docker.
Docker allows you to package Mercury together with Python and all dependencies, making deployment predictable and reproducible across different machines.

Create a Dockerfile

Start by creating a file named Dockerfile in your project directory.

The following Dockerfile uses a lightweight Python image, installs Mercury, and starts the Mercury server on port 8888.

Dockerfile

FROM python:3.12-slim

# Install Mercury
RUN pip install mercury==3.0.0a2

# You can also install needed packages here,
# For example install pandas
# RUN pip install pandas

# Directory where notebooks will be mounted
WORKDIR /workspace

# Mercury default port
EXPOSE 8888

# Start Mercury server
CMD ["mercury", "--ip=0.0.0.0", "--no-browser", "--allow-root"]

Workspace directory

The /workspace directory is important.
Your local notebooks directory will be mounted there so Mercury can discover and serve your notebooks.

Docker commands

Below are the most common Docker commands you will need when working with the Mercury container.

Build the Docker image

Build the Docker image from the Dockerfile and tag it as mercury-server:

docker build -t mercury-server .

This command only needs to be run again if you change the Dockerfile code.

Run the container (foreground mode)

This mode is useful during development. The container runs in the foreground and is automatically removed when you stop it.

docker run --rm -it \
  -p 8888:8888 \
  -v /my/directory/with/notebooks:/workspace \
  mercury-server

After starting, open your browser and navigate to:

http://localhost:8888

Mount notebooks directory

The -v option mounts your local notebooks directory /my/directory/with/notebooks into the container.

Run the container (background mode)

For longer-running sessions or server-like usage, run Mercury in detached mode by adding -d flag:

docker run -d --name mercury-server \
  -p 8888:8888 \
  -v /my/directory/with/notebooks:/workspace \
  mercury-server

The container will continue running in the background until you stop it explicitly.

View container logs

To inspect Mercury logs or verify that the server started correctly:

docker logs -f mercury-server

Press Ctrl + C to stop following the logs.

Open a shell inside the container (debugging)

If you need to inspect the container environment or verify mounted files:

docker exec -it mercury-server /bin/sh

For example, you can list mounted notebooks:

ls -la /workspace

Stop the container

If Mercury is running in background mode, stop it with:

docker stop mercury-server

Stop and remove the container

To stop and remove the container in a single command:

docker rm -f mercury-server