Installation Guide

Prerequisites

Before installing RedundaNet, make sure you have:

• Python 3.11+ (for the CLI and development)
• Docker & Docker Compose (for containerized deployment)
• GPG (for node authentication)
• Git (for manifest synchronization)

Installation methods

1. PyPI (recommended)

The simplest way to install the RedundaNet CLI:

pip install redundanet

# Verify
redundanet --version

2. Poetry (for development)

Clone the repository and install with Poetry:

git clone https://github.com/adefilippo83/redundanet.git
cd redundanet

# Install Poetry if you don't have it
curl -sSL https://install.python-poetry.org | python3 -

poetry install
poetry shell
redundanet --version

3. Docker deployment (for running services)

Clone the repository and start the services from the docker/ directory:

git clone https://github.com/adefilippo83/redundanet.git
cd redundanet/docker

# As a storage node
docker compose --profile storage up -d

# As a client
docker compose --profile client up -d

To explicitly refresh to the latest published images:

docker compose pull
docker compose up -d

Choosing the image source and version

Two environment variables override which images are used:

# Pin to a released version
VERSION=2.3.0 docker compose --profile storage up -d

Building the images from source

To build locally instead of pulling (for development, an unsupported architecture, or air-gapped hosts), overlay docker-compose.build.yml:

docker compose -f docker-compose.yml -f docker-compose.build.yml build
docker compose -f docker-compose.yml -f docker-compose.build.yml --profile storage up -d

The locally built images are tagged with the same names as the pulled ones, so a later docker compose up -d (without the overlay) reuses them. For live-reload development, use docker-compose.dev.yml instead.

4. Raspberry Pi image

On first boot the Pi pulls the prebuilt container images for its architecture (arm64 for 64-bit Raspberry Pi OS, arm/v7 for 32-bit) straight from GHCR, so it never has to compile anything locally.

1. Download the pre-built image from GitHub Releases.
2. Flash it to an SD card with Raspberry Pi Imager.
3. Boot the Pi and SSH in: ssh redundanet@redundanet.local (password: redundanet).
4. Change the password immediately: passwd.
5. Configure the node: redundanet init.

Download latest image →

System requirements

Minimum

Recommended

Platform support

Linux (primary)

Fully supported on Ubuntu 20.04+, Debian 11+, Raspberry Pi OS, CentOS 8+, Fedora 35+, and Arch Linux.

macOS

Supported for development and CLI usage. Docker Desktop is required for containerized deployment.

Windows

Supported via WSL2. Native Windows support is experimental.

Container image architectures

The published images (ghcr.io/adefilippo83/redundanet-*) are multi-arch, so docker compose pull selects the correct one automatically:

For any other architecture, build the images from source with the docker-compose.build.yml overlay (see above).

Network requirements

Ports

Firewall configuration

For publicly accessible nodes, open port 655:

# UFW (Ubuntu)
sudo ufw allow 655/tcp
sudo ufw allow 655/udp

# firewalld (CentOS/Fedora)
sudo firewall-cmd --permanent --add-port=655/tcp
sudo firewall-cmd --permanent --add-port=655/udp
sudo firewall-cmd --reload

GPG key setup

GPG keys authenticate nodes and must be published to a public keyserver. The key must be RSA — it doubles as the node's Tinc transport key.

Using the RedundaNet CLI (recommended)

# Generate a new GPG key
redundanet node keys generate --name my-node --email you@example.com

# List your keys to get the key ID
redundanet node keys list

# Publish to keyservers
redundanet node keys publish --key-id YOUR_KEY_ID

Using standard GPG commands

# Generate a new key — choose RSA and RSA, 4096 bits
gpg --full-generate-key

# List keys to get your key ID
gpg --list-keys --keyid-format long

# Export to a keyserver
gpg --keyserver keys.openpgp.org --send-keys YOUR_KEY_ID

Verification

After installation, confirm everything works:

# Check the CLI
redundanet --version

# Check GPG keys
redundanet node keys list

# Check Docker (run from the docker/ directory)
docker compose config

# Check node status
redundanet status

Next steps

• Join the network
• Source & documentation on GitHub
• Releases