geti2p/i2p.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

⁠Minimal

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

services:
  i2p:
    image: geti2p/i2p:latest
    restart: unless-stopped
    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: unless-stopped
    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: unless-stopped
    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
      - "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 54321 with a random port number greater than 1024.

docker run -d \
    --name i2p \
    -e JVM_XMX=512m \
    -e EXT_PORT=54321 \
    -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 54321:12345 \
    -p 54321: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

⁠Ports Reference

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

⁠Building from Source

Build the image locally:

docker build -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 (no EXT_PORT set): The router can only make outgoing connections. This works but reduces performance and your ability to contribute to the network.
• Non-Firewalled (EXT_PORT set and port published): The router accepts incoming connections. This improves performance and helps the I2P network.

To achieve non-firewalled status, you must:

1. Set the EXT_PORT environment variable
2. Publish that port for both TCP and UDP
3. Ensure your firewall/router allows traffic on that port

⁠Binding and Remote Access

All services except I2NP are bound to 127.0.0.1 by default. This means they are only accessible from the Docker host machine (via published ports) and not from the network.

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 — but only do this on a trusted network, as it exposes the console and proxies to anyone who can reach the container.

⁠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=54321 -p 54321:12345 -p 54321: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.