Padduck

A modern IP Address Management (IPAM) platform built with Go, React, and PostgreSQL.

Purpose

Replace spreadsheet-based IP tracking with a structured, API-first system.

Stack

• Backend: Go (Fiber)
• Frontend: React (Vite)
• Database: PostgreSQL
• Deployment: Docker Compose + GitHub Container Registry

Quick Start

You do not need to clone this repository or build images locally. The backend and frontend images are published to GitHub Container Registry; only the Compose file is required on the host.

mkdir padduck
cd padduck
curl -fsSLO https://raw.githubusercontent.com/lima3w/padduck/main/docker-compose.yml
docker compose pull
docker compose up -d

On first startup, the backend creates a persistent MFA encryption key in ./data/backend/mfa-encryption-key if MFA_ENCRYPTION_KEY is not set. Before using this in a shared or production environment, create a .env file and set a strong POSTGRES_PASSWORD.

Open http://localhost:3000 and log in as admin. The generated password is printed to the backend log on first boot.

Configuration

Configuration is read from environment variables. Docker Compose will also read a local .env file for variable interpolation if one is present — it is not created automatically.

Variable	Default	Description
POSTGRES_USER	padduck	PostgreSQL username
POSTGRES_PASSWORD	padduck	PostgreSQL password
POSTGRES_DB	padduck	PostgreSQL database name
DATABASE_URL	derived	Overrides the individual PostgreSQL variables
ADMIN_PASSWORD	(generated)	Initial admin password; printed to logs on first boot if unset
RESET_ADMIN_PASSWORD	false	Force-reset the admin password on next boot
MFA_ENCRYPTION_KEY	generated if unset	Optional override; 64 hex characters; generate with openssl rand -hex 32
SESSION_COOKIE_SECURE	auto	auto marks session cookies secure when behind HTTPS; set true or false to override
FRONTEND_PORT	3000	Host port the UI is exposed on
IMAGE_TAG	latest	Pin to a specific release (e.g. v1.30.0)

Update checks can be enabled under Admin Settings → Updates. The backend checks the GitHub releases API automatically — no configuration required.

Documentation

Full documentation is on the GitHub Wiki, including:

• Installation Guide
• Configuration
• User Guide
• API Documentation
• Troubleshooting