# 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 (P2P TCP/QUIC transports), 5001 (RPC API) and 8080 (Gateway):

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


    The API port provides admin-level access to your IPFS node. See RPC API docs for more information.

  4. Watch the ipfs log:

    docker logs -f ipfs_host
  5. Wait for IPFS to start:

    Gateway (readonly) server
    listening on /ip4/

    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 -p 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 -p 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 -p 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