Pubky Docker

Pubky Docker is a Docker Compose orchestration that provides a one-click local development environment for running the complete Pubky Social (App) stack. It’s designed for developers who want to experiment with the full Pubky ecosystem or test components in an isolated environment.

Overview

Pubky Docker orchestrates the following components:

PKARR Relay - DHT relay for public key-addressable records
Pubky Homeserver - Decentralized data storage instance
Pubky Nexus - Social media indexer and aggregator
Pubky App - Social media client frontend

The orchestration includes all necessary supporting infrastructure (PostgreSQL, Neo4j, Redis) and is configurable for both testnet and mainnet environments.

When to Use Pubky Docker

✅ Use Pubky Docker When:

Experimenting with the complete Pubky Social stack
Developing or testing Pubky Nexus integrations
Building custom social media frontends
Testing Homeserver configurations
Learning how all Pubky components interact
Debugging cross-component issues

❌ Don’t Use Pubky Docker When:

Building applications using Pubky Core (use SDK libraries instead)
Developing simple Pubky integrations (use official client libraries)
Just testing basic read/write operations

For application development, use the official client libraries:

JavaScript: @synonymdev/pubky
Rust: pubky

Quick Start

Using Public Docker Images

This is the fastest way to get started. All images are available on Docker Hub.

Clone the repository:

git clone https://github.com/pubky/pubky-docker.git
cd pubky-docker

Configure environment:

cp .env-sample .env
# Edit .env to set NETWORK=mainnet or NETWORK=testnet

Start the stack:

docker compose up -d

Building From Source

If you need to modify components or build custom versions:

Clone all required repositories at the same directory level:

# Create a workspace directory
mkdir pubky-workspace && cd pubky-workspace

# Clone all repositories
git clone https://github.com/pubky/pubky-docker.git
git clone https://github.com/pubky/pkarr.git
git clone https://github.com/pubky/pubky-core.git
git clone https://github.com/pubky/pubky-nexus.git
git clone https://github.com/pubky/pubky-app.git

Configure and start:

cd pubky-docker
cp .env-sample .env
# Edit .env as needed
docker compose up

The directory structure must be:

pubky-workspace/
├── pubky-docker/
├── pkarr/
├── pubky-core/
├── pubky-nexus/
└── pubky-app/

Stack Components

1. PKARR Relay (Port 6882)

Local DHT relay for public key-addressable resource records. Enables domain resolution for Pubky identities.

Configuration: pkarr.config.toml

2. Pubky Homeserver (Ports 6286-6288, 15411-15412)

Local instance of a Pubky Homeserver with PostgreSQL backend.

Configuration: homeserver.config.toml

Database: PostgreSQL (Port 5432)

Endpoints:

6287: Primary HTTP API
6286: Admin API
6288: Metrics
15411-15412: HTTP relay

3. Pubky Nexus (Ports 8080-8081)

Social media indexer and aggregator with graph database and search capabilities.

Configuration: pubky-nexus-config-{testnet|mainnet}.toml

Dependencies:

Neo4j graph database (Ports 7474, 7687)
Redis search index (Ports 6379, 8001)

Endpoints:

8080: Main API
8081: Admin/metrics

4. Pubky App (Port 4200)

Next.js-based social media frontend configured to use the local stack.

Access: http://localhost:4200

Configuration

Environment Variables

Configuration is managed through a .env file. Copy the sample and adjust as needed:

cp .env-sample .env

See .env-sample in the repository for all available variables and their defaults.

Network Configuration

The stack uses a custom Docker bridge network (172.18.0.0/16) with static IPs:

Service	IP	External Ports
PKARR	172.18.0.2	6882
Nexus	172.18.0.3	8080, 8081
Homeserver	172.18.0.4	6286-6288, 15411-15412
Neo4j	172.18.0.5	7474, 7687
Redis	172.18.0.6	6379, 8001
Client	172.18.0.7	4200
Postgres	172.18.0.9	5432

Usage Examples

Start the Full Stack

docker compose up -d

View Logs

# All services
docker compose logs -f

# Specific service
docker compose logs -f homeserver
docker compose logs -f nexusd

Stop the Stack

docker compose down

Rebuild After Code Changes

docker compose build
docker compose up -d

Reset All Data

docker compose down -v
rm -rf .storage/

Development Workflows

Testing Homeserver Changes

Modify code in ../pubky-core/
Rebuild Homeserver:

docker compose build homeserver
docker compose up -d homeserver

Testing Nexus Changes

Modify code in ../pubky-nexus/
Rebuild nexus:

docker compose build nexusd
docker compose up -d nexusd

Testing Frontend Changes

Modify code in ../pubky-app/
Rebuild client:

docker compose build client
docker compose up -d client

Access Monitoring Tools

Neo4j Browser: http://localhost:7474
Redis Insight: http://localhost:8001
Pubky App: http://localhost:4200

Data Persistence

All data is stored in the .storage/ directory:

.storage/
├── pkarr/          # PKARR relay cache
├── postgres/       # Homeserver database
├── neo4j/          # Nexus graph data
├── redis/          # Nexus search index
└── static/         # Nexus static files

This directory is gitignored. To reset your environment, simply delete it.

Troubleshooting

Containers Won’t Start

Check if ports are already in use:

# Check port availability
lsof -i :4200 -i :6882 -i :8080

Database Connection Errors

Ensure PostgreSQL is healthy:

docker compose ps postgres
docker compose logs postgres

Nexus Can’t Connect to Homeserver

Verify Homeserver is running and accessible:

curl http://localhost:6287/
docker compose logs homeserver

Reset a Specific Service

# Stop service
docker compose stop nexusd

# Remove its data
rm -rf .storage/neo4j .storage/redis

# Restart
docker compose up -d nexusd

Architecture

The Pubky Docker stack demonstrates the full architecture of a Pubky Social application:

┌─────────────────────────────────────────────────────┐
│                   Browser                           │
│              (localhost:4200)                       │
└────────────────────┬────────────────────────────────┘
                     │
┌────────────────────▼────────────────────────────────┐
│                Pubky App (Client)                   │
│            Next.js Frontend                         │
└────────────┬──────────────────────┬─────────────────┘
             │                      │
    ┌────────▼─────────┐   ┌────────▼──────────┐
    │  Pubky Nexus     │   │ Pubky Homeserver  │
    │  (Social API)    │   │  (User Storage)   │
    │  - Neo4j Graph   │   │  - PostgreSQL     │
    │  - Redis Search  │   │  - File Storage   │
    └────────┬─────────┘   └────────┬──────────┘
             │                      │
             └──────────┬───────────┘
                        │
                 ┌──────▼───────┐
                 │ PKARR Relay  │
                 │ (DHT/DNS)    │
                 └──────────────┘