geti2p/i2p repository overview

⁠I2P in Docker

I2P is an anonymous overlay network — a network within a network. It is intended to protect communication from surveillance and monitoring by third parties such as ISPs.

⁠Available Images

Both images are identical and support the following architectures:

⁠Quick Start

The fastest way to get I2P running:

docker run -d \
    --name i2p \
    -e JVM_XMX=512m \
    -v i2pconfig:/i2p/.i2p \
    -p 127.0.0.1:7657:7657 \
    -p 127.0.0.1:4444:4444 \
    geti2p/i2p:latest

Then open your browser to http://127.0.0.1:7657⁠ to access the I2P Router Console and complete the setup wizard.

⁠Docker Compose Examples

These examples use restart: on-failure:3. This retries unexpected failures up to 3 times, while a normal shutdown from the Router Console exits cleanly and stays stopped. Adjust the retry count for your deployment.

⁠Minimal

Runs the router console and HTTP proxy only. Good for trying I2P out.

services:
  i2p:
    image: geti2p/i2p:latest
    restart: on-failure:3
    volumes:
      - ./i2pconfig:/i2p/.i2p
    ports:
      - "127.0.0.1:7657:7657"   # Router Console
      - "127.0.0.1:4444:4444"   # HTTP Proxy

⁠Recommended

Includes persistent volumes, memory limits, and an external port for non-firewalled operation. Replace 12345 with a random port number greater than 1024.

services:
  i2p:
    image: geti2p/i2p:latest
    restart: on-failure:3
    environment:
      - JVM_XMX=512m
      - EXT_PORT=12345
    volumes:
      - ./i2pconfig:/i2p/.i2p
      - ./i2ptorrents:/i2psnark
    ports:
      - "127.0.0.1:7657:7657"   # Router Console
      - "127.0.0.1:4444:4444"   # HTTP Proxy
      - "127.0.0.1:6668:6668"   # IRC Proxy
      - "12345:12345"           # I2NP TCP
      - "12345:12345/udp"       # I2NP UDP

⁠Full (all services)

Exposes every available service. Only use this if you need all of them.

services:
  i2p:
    image: geti2p/i2p:latest
    restart: on-failure:3
    environment:
      - JVM_XMX=512m
      - EXT_PORT=12345
    volumes:
      - ./i2pconfig:/i2p/.i2p
      - ./i2ptorrents:/i2psnark
    ports:
      - "127.0.0.1:4444:4444"   # HTTP Proxy
      - "127.0.0.1:4445:4445"   # HTTPS Proxy
      - "127.0.0.1:6668:6668"   # IRC Proxy
      - "127.0.0.1:7654:7654"   # I2CP Protocol
      - "127.0.0.1:7656:7656"   # SAM Bridge
      - "127.0.0.1:7657:7657"   # Router Console
      - "127.0.0.1:7658:7658"   # I2P Site (eepsite)
      - "127.0.0.1:7659:7659"   # SMTP Proxy
      - "127.0.0.1:7660:7660"   # POP3 Proxy
      - "127.0.0.1:7670:7670"   # I2P Git Repositories SSH Access
      - "12345:12345"           # I2NP TCP
      - "12345:12345/udp"       # I2NP UDP

⁠Docker Run Examples

⁠Minimal

docker run -d \
    --name i2p \
    -v i2pconfig:/i2p/.i2p \
    -p 127.0.0.1:7657:7657 \
    -p 127.0.0.1:4444:4444 \
    geti2p/i2p:latest

⁠Recommended (with external port)

Replace 12345 with a random port number greater than 1024.

docker run -d \
    --name i2p \
    -e JVM_XMX=512m \
    -e EXT_PORT=12345 \
    -v i2pconfig:/i2p/.i2p \
    -v i2ptorrents:/i2psnark \
    -p 127.0.0.1:4444:4444 \
    -p 127.0.0.1:6668:6668 \
    -p 127.0.0.1:7657:7657 \
    -p 12345:12345 \
    -p 12345:12345/udp \
    geti2p/i2p:latest

⁠Low memory (256MB heap)

docker run -d \
    --name i2p \
    -e JVM_XMX=256m \
    -v i2pconfig:/i2p/.i2p \
    -p 127.0.0.1:7657:7657 \
    -p 127.0.0.1:4444:4444 \
    geti2p/i2p:latest

⁠Environment Variables

If either I2P_UID or I2P_GID is set, the entrypoint remaps the i2p account before fixing ownership and starting the router. Startup fails with a clear error if the requested UID/GID is already used by a different user/group in the container.

⁠Ports Reference

IP_ADDR auto-derivation defaults to 127.0.0.1 in host network mode, and to the container route-source IP in bridge/default Docker networking.

Which ports should I publish?

• Always: 7657 (Router Console) and 4444 (HTTP Proxy) — these are the minimum to use I2P.
• Recommended: 12345 / EXT_PORT (I2NP) — allows incoming connections, improving network integration and performance.
• Optional: 6668 (IRC), 7656 (SAM), and others as needed.

⁠Volumes

Bind mount example:

mkdir -p ./i2pconfig ./i2ptorrents
docker run -v ./i2pconfig:/i2p/.i2p -v ./i2ptorrents:/i2psnark ...

Named volume example:

docker run -v i2pconfig:/i2p/.i2p -v i2ptorrents:/i2psnark ...

Bind mount with host UID/GID mapping:

docker run \
  -e I2P_UID="$(id -u)" \
  -e I2P_GID="$(id -g)" \
  -v ./i2pconfig:/i2p/.i2p \
  -v ./i2ptorrents:/i2psnark \
  ...

⁠Building from Source

Build the image locally:

docker build --build-arg TARGETARCH=amd64 -t i2p .

Multi-architecture build (requires Docker Buildx):

docker buildx build --platform linux/amd64,linux/arm64,linux/arm/v7 -t i2p .

⁠Networking and Security

⁠External Port Selection

The default I2NP port is 12345. You should change this to a random port greater than 1024 when deploying. Using the default port makes it easy for others to identify that you are running I2P in Docker.

# Pick a random port
EXT_PORT=$(shuf -i 1025-65535 -n 1)
echo "Using port: $EXT_PORT"

⁠Firewalled vs Non-Firewalled

• Firewalled (external I2NP port not reachable): The router can only make outgoing connections. This works but reduces performance and your ability to contribute to the network.
• Non-Firewalled (external I2NP port reachable): The router accepts incoming connections. This improves performance and helps the I2P network.

To achieve non-firewalled status, you must:

1. Set EXT_PORT (or use the default 12345)
2. Publish that same port number for both host and container on TCP and UDP
3. Ensure your firewall/router allows traffic on that port

⁠Binding and Remote Access

All services except I2NP use IP_ADDR as their bind address (Router Console, I2CP, SAM, and client tunnels).

If IP_ADDR is unset, the entrypoint derives it automatically:

• Host network mode: Uses 127.0.0.1 to keep services local to the host.
• Bridge/default Docker network: Uses the container's default-route source IPv4 (typically the container bridge IP), with fallback to hostname -i, then 127.0.0.1.

This default behavior is intentional: in bridge mode, binding to the container IP allows published ports and same-network containers to reach services. In host mode, binding to loopback avoids exposing admin/proxy ports broadly.

To access the Router Console from a remote machine, use an SSH tunnel:

ssh -L 7657:127.0.0.1:7657 user@your-server
# Then open http://127.0.0.1:7657 in your local browser

Alternatively, set IP_ADDR=0.0.0.0 to bind services to all interfaces inside the container. Do this only when required and only on a trusted network, as it may expose the console and proxies to anyone who can reach published host ports.

⁠Advanced Configuration

⁠Custom router.config

You can mount a custom configuration file to override defaults:

docker run -v ./my-router.config:/i2p/router.config ...

The default settings disable automatic updates (router.updateDisabled=true) since the Docker image should be updated by pulling a new image.

⁠Enabling the SAM Bridge

The SAM (Simple Anonymous Messaging) bridge allows external applications to use the I2P network. It is disabled by default. To enable it:

1. Open the Router Console at http://127.0.0.1:7657⁠
2. Navigate to I2CP settings or Clients configuration
3. Enable the SAM Bridge client

Then publish port 7656 to use it from the host:

docker run -p 127.0.0.1:7656:7656 ...

⁠Hosting an I2P Site (Eepsite)

The built-in web server (eepsite) is disabled by default. To enable it:

1. Open the Router Console at http://127.0.0.1:7657⁠
2. Navigate to Hidden Services Manager
3. Start the "I2P Webserver" tunnel

Place your website files in the eepsite directory within the config volume.

⁠Troubleshooting

⁠Router shows "Firewalled" status

Set the EXT_PORT environment variable and publish the port:

docker run -e EXT_PORT=12345 -p 12345:12345 -p 12345:12345/udp ...

Ensure the port is open in your host firewall and any upstream router/NAT.

⁠Cannot access the Router Console

• Verify port 7657 is published: docker port i2p
• Ensure you're binding to 127.0.0.1:7657 on the host
• Check that the container is running: docker ps
• Check container logs: docker logs i2p

⁠High memory usage

Lower the JVM heap limit:

docker run -e JVM_XMX=256m ...

The default is 512m. For systems with limited RAM (e.g., Raspberry Pi), 256m works but may reduce performance.

⁠Container won't start

Check the logs for errors:

docker logs i2p

Common causes:

• Volume permission issues — ensure the mounted directories are writable
• Port conflicts — check if another process is using the same ports

⁠Updating

Since automatic updates are disabled in the Docker image, update by pulling the latest image:

docker pull geti2p/i2p:latest
docker stop i2p
docker rm i2p
# Re-run your docker run command

Or with Docker Compose:

docker compose pull
docker compose up -d

Your configuration and router identity are preserved in the /i2p/.i2p volume.