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
Section titled “Overview”Pubky Docker orchestrates the following components:
- Pubky Homeserver - Decentralized data storage instance
- Pubky Nexus - Social media indexer and aggregator
- Homegate - Signup verification service for preventing automated signup spam
- pubky.app - Social media client frontend
Third-party infrastructure images (Postgres, Neo4j, Redis, Redis Insight, WireMock) are pulled from their public registries.
When to Use Pubky Docker
Section titled “When to Use Pubky Docker”✅ Use Pubky Docker When:
Section titled “✅ 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:
Section titled “❌ 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
Section titled “Quick Start”Using Public Docker Images
Section titled “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.gitcd pubky-docker- Configure environment:
cp .env-sample .env# Edit .env to set NETWORK=mainnet or NETWORK=testnet- Start the stack:
docker compose up -dFor source builds, see Local Setup From Source in the Pubky Docker README.
Stack Components
Section titled “Stack Components”1. Pubky Homeserver
Section titled “1. Pubky Homeserver”Local instance of Pubky Homeserver with PostgreSQL backend.
Configuration: homeserver.config.toml
Database: PostgreSQL (Port 5432)
Endpoints:
6287: Primary HTTP API6286: Admin API6288: Metrics15411-15412: HTTP relay
2. Pubky Nexus
Section titled “2. Pubky Nexus”Pubky Nexus 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 (Port 6379)
Endpoints:
8080: Main API8081: Admin/metrics
3. Homegate
Section titled “3. Homegate”Homegate signup verification service configured for local development.
Configuration: homegate.config.toml
Access: http://localhost:6300
4. pubky.app
Section titled “4. pubky.app”pubky.app social media frontend configured to use the local stack.
Access: http://localhost:3000
Configuration
Section titled “Configuration”Environment Variables
Section titled “Environment Variables”Configuration is managed through a .env file. Copy the sample and adjust as needed:
cp .env-sample .envSee .env-sample in the repository for all available variables and their defaults.
Network Configuration
Section titled “Network Configuration”The stack uses a custom Docker bridge network (172.18.0.0/16) with static IPs:
| Service | IP | External Ports |
|---|---|---|
| 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 |
| Redis Insight | 172.18.0.7 | 5540 |
| pubky.app | 172.18.0.8 | 3000 |
| Postgres | 172.18.0.9 | 5432 |
| Homegate | 172.18.0.10 | 6300 |
Usage Examples
Section titled “Usage Examples”Start the Full Stack
Section titled “Start the Full Stack”docker compose up -dView Logs
Section titled “View Logs”# All servicesdocker compose logs -f
# Specific servicedocker compose logs -f homeserverdocker compose logs -f nexusdStop the Stack
Section titled “Stop the Stack”docker compose downRebuild After Code Changes
Section titled “Rebuild After Code Changes”docker compose builddocker compose up -dReset All Data
Section titled “Reset All Data”docker compose down -vrm -rf .storage/Development Workflows
Section titled “Development Workflows”Testing Homeserver Changes
Section titled “Testing Homeserver Changes”- Modify code in
../pubky-core/ - Rebuild Homeserver:
docker compose build homeserverdocker compose up -d homeserverTesting Nexus Changes
Section titled “Testing Nexus Changes”- Modify code in
../pubky-nexus/ - Rebuild nexus:
docker compose build nexusddocker compose up -d nexusdTesting Frontend Changes
Section titled “Testing Frontend Changes”- Modify code in
../pubky-app/ - Rebuild pubky.app:
docker compose build pubky-appdocker compose up -d pubky-appAccess Monitoring Tools
Section titled “Access Monitoring Tools”- Neo4j Browser: http://localhost:7474
- Redis Insight: http://localhost:5540
- pubky.app: http://localhost:3000
Data Persistence
Section titled “Data Persistence”All data is stored in the .storage/ directory:
.storage/├── postgres/ # Homeserver database├── homegate/ # Homegate data├── neo4j/ # Nexus graph data├── redis/ # Nexus search index└── static/ # Nexus static filesThis directory is gitignored. To reset your environment, simply delete it.
Troubleshooting
Section titled “Troubleshooting”Containers Won’t Start
Section titled “Containers Won’t Start”Check if ports are already in use:
# Check port availabilitylsof -i :3000 -i :6287 -i :8080 -i :6300Database Connection Errors
Section titled “Database Connection Errors”Ensure PostgreSQL is healthy:
docker compose ps postgresdocker compose logs postgresNexus Can’t Connect to Homeserver
Section titled “Nexus Can’t Connect to Homeserver”Verify Homeserver is running and accessible:
curl http://localhost:6287/docker compose logs homeserverReset a Specific Service
Section titled “Reset a Specific Service”# Stop servicedocker compose stop nexusd
# Remove its datarm -rf .storage/neo4j .storage/redis
# Restartdocker compose up -d nexusdArchitecture
Section titled “Architecture”The Pubky Docker stack demonstrates the full architecture of a Pubky Social application:
┌───────────────────────────────────────────────────────────────┐│ Browser ││ (localhost:3000) │└───────────────────────────────┬───────────────────────────────┘ │┌───────────────────────────────▼───────────────────────────────┐│ Docker Compose stack ││ ││ ┌─────────────────────────────────────────────────────────┐ ││ │ pubky.app (Client) │ ││ │ Next.js Frontend │ ││ └────────────┬──────────────────────┬─────────────────────┘ ││ │ │ ││ ┌────────▼─────────┐ ┌────────▼──────────┐ ││ │ Pubky Nexus │ │ Pubky Homeserver │ ││ │ (Social API) │ │ (User Storage) │ ││ │ - Neo4j Graph │ │ - PostgreSQL │ ││ │ - Redis Search │ │ - File Storage │ ││ └──────────────────┘ └────────┬──────────┘ ││ │ ││ ┌──────▼───────┐ ││ │ Homegate │ ││ │ (Signup) │ ││ └──────────────┘ │└───────────────────────────────┬───────────────────────────────┘ │ ▼┌───────────────────────────────────────────────────────────────┐│ Synonym-hosted PKARR Relay ││ used by the configured stack │└───────────────────────────────────────────────────────────────┘- Repository: https://github.com/pubky/pubky-docker
- Upstream: https://github.com/pubky/pubky-docker
- Docker Hub: https://hub.docker.com/u/synonymsoft
Related Documentation
Section titled “Related Documentation”- Pubky Core - Core protocol and SDK
- Pubky Nexus - Social media indexer
- Homegate - Signup verification service
- pubky.app - Frontend application
- Pubky Homeservers - Homeserver architecture