Run IPFS inside Docker

You can run IPFS inside Docker to simplify your deployment processes, as well as horizontally scale your IPFS infrastructure.

Set up

1. Grab the IPFS docker image hosted at hub.docker.com/r/ipfs/go-ipfs (opens new window).

2. To make files visible inside the container, you need to mount a host directory with the -v option to Docker. Choose a directory that you want to use to import and export files from IPFS. You should also choose a directory to store IPFS files that will persist when you restart the container.

   export ipfs_staging=</absolute/path/to/somewhere/>
   export ipfs_data=</absolute/path/to/somewhere_else/>
   

3. Start a container running ipfs and expose ports 4001, 5001 and 8080:

   docker run -d --name ipfs_host -v $ipfs_staging:/export -v $ipfs_data:/data/ipfs -p 4001:4001 -p 4001:4001/udp -p 127.0.0.1:8080:8080 -p 127.0.0.1:5001:5001 ipfs/go-ipfs:latest
   

4. Watch the ipfs log:

   docker logs -f ipfs_host
   

5. Wait for IPFS to start:

   Gateway (readonly) server
   listening on /ip4/0.0.0.0/tcp/8080
   

   You can now stop watching the log.

6. Run IPFS commands with docker exec ipfs_host ipfs <args...>. For example:

   To connect to peers:

   docker exec ipfs_host ipfs swarm peers
   

   To add files:

   cp -r <something> $ipfs_staging
   docker exec ipfs_host ipfs add -r /export/<something>
   

7. Stop the running container:

   docker stop ipfs_host
   

When starting a container running ipfs for the first time with an empty data directory, it will call ipfs init to initialize configuration files and generate a new keypair. At this time, you can choose which profile to apply using the IPFS_PROFILE environment variable:

docker run -d --name ipfs_host -e IPFS_PROFILE=server -v $ipfs_staging:/export -v $ipfs_data:/data/ipfs -p 4001:4001 -p 4001:4001/udp -p 127.0.0.1:8080:8080 -p 127.0.0.1:5001:5001 ipfs/go-ipfs:latest

Private swarms inside Docker

It is possible to initialize the container with a swarm key file (/data/ipfs/swarm.key) using the variables IPFS_SWARM_KEY and IPFS_SWARM_KEY_FILE. The IPFS_SWARM_KEY creates swarm.key with the contents of the variable itself, while IPFS_SWARM_KEY_FILE copies the key from a path stored in the variable. The IPFS_SWARM_KEY_FILE overwrites the key generated by IPFS_SWARM_KEY.

docker run -d --name ipfs_host -e IPFS_SWARM_KEY=<your swarm key> -v $ipfs_staging:/export -v $ipfs_data:/data/ipfs -p 4001:4001 -p 4001:4001/udp -p 127.0.0.1:8080:8080 -p 127.0.0.1:5001:5001 ipfs/go-ipfs:latest

The swarm key initialization can also be done using docker secrets, and requires docker swarm or docker-compose:

cat your_swarm.key | docker secret create swarm_key_secret -
docker run -d --name ipfs_host --secret swarm_key_secret -e IPFS_SWARM_KEY_FILE=/run/secrets/swarm_key_secret -v $ipfs_staging:/export -v $ipfs_data:/data/ipfs -p 4001:4001 -p 4001:4001/udp -p 127.0.0.1:8080:8080 -p 127.0.0.1:5001:5001 ipfs/go-ipfs:latest

Key rotation inside Docker

It is possible to do key rotation in an ephemeral container that is temporarily executing against a volume that is mounted under /data/ipfs:

# given container named 'ipfs-test' that persists repo at /path/to/persisted/.ipfs
docker run -d --name ipfs-test -v /path/to/persisted/.ipfs:/data/ipfs ipfs/go-ipfs:v0.7.0 
docker stop ipfs-test  

# key rotation works like this (old key saved under 'old-self')
docker run --rm -it -v /path/to/persisted/.ipfs:/data/ipfs ipfs/go-ipfs:v0.7.0 key rotate -o old-self -t ed25519
docker start ipfs-test # will start with the new key