Search

SearchSearch

Pubky Docker

Jan 30, 20265 min read

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:

  1. Pkarr Relay - DHT relay for public key-addressable records
  2. Pubky Homeserver - Decentralized data storage instance
  3. Pubky Nexus - Social media indexer and aggregator
  4. 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:

Quick Start

Using Public Docker Images

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

  1. Clone the repository:
git clone https://github.com/pubky/pubky-docker.git
cd pubky-docker
  1. Configure environment:
cp .env-sample .env
# Edit .env to set NETWORK=mainnet or NETWORK=testnet
  1. Start the stack:
docker compose up -d

Building From Source

If you need to modify components or build custom versions:

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

The .env file controls key configuration:

# Network Selection
NETWORK=testnet  # or mainnet
 
# Image Tags (when using public images)
REGISTRY=synonymsoft
PUBKY_APP_TAG=latest
PUBKY_NEXUS_TAG=latest
HOMESERVER_TAG=latest
PKARR_TAG=latest
 
# Database
POSTGRES_USER=homeserver
POSTGRES_PASSWORD=homeserver
POSTGRES_DB=homeserver
 
# Frontend Configuration
NEXT_PUBLIC_HOMESERVER=8pinxxgqs41n4aididenw5apqp1urfmzdztr8jt4abrkdn435ewo
NEXT_PUBLIC_NEXUS=http://localhost:8080
NEXT_PUBLIC_TESTNET=true
HTTP_RELAY=http://localhost:15412/link/
NEXT_PUBLIC_PKARR_RELAYS=["https://pkarr.pubky.app","https://pkarr.pubky.org"]

Network Configuration

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

ServiceIPExternal Ports
Pkarr172.18.0.26882
Nexus172.18.0.38080, 8081
Homeserver172.18.0.46286-6288, 15411-15412
Neo4j172.18.0.57474, 7687
Redis172.18.0.66379, 8001
Client172.18.0.74200
Postgres172.18.0.95432

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

  1. Modify code in ../pubky-core/
  2. Rebuild homeserver:
docker compose build homeserver
docker compose up -d homeserver

Testing Nexus Changes

  1. Modify code in ../pubky-nexus/
  2. Rebuild nexus:
docker compose build nexusd
docker compose up -d nexusd

Testing Frontend Changes

  1. Modify code in ../pubky-app/
  2. Rebuild client:
docker compose build client
docker compose up -d client

Access Monitoring Tools

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)    │
                 └──────────────┘

Graph View