Self-Hosting Guide

Want to run Posthoot on your own servers? This guide will walk you through setting up your own instance. It’s actually pretty straightforward - we’ve made it as simple as possible.

What you’ll need

Before we start, make sure you have these installed:

Go 1.21+ - Download here
PostgreSQL 14+ - Download here
Redis 6+ - Download here
Git - Download here

Server specs

For a basic setup, you’ll want:

CPU: 2+ cores (more is better)
RAM: 4GB minimum, 8GB recommended
Storage: 20GB for database and logs
Network: Stable internet connection

If you’re just testing locally, you can get away with less, but for production, these are the minimums we’d recommend.

Quick Start

1. Get the code

git clone https://github.com/posthoot/posthoot-backend.go.git
cd posthoot-backend

2. Set up your environment

Copy the example config and edit it:

cp .env.example .env

Here’s what you need to configure in your .env file:

# Server settings
SERVER_HOST=0.0.0.0
SERVER_PORT=8080
PUBLIC_URL=http://your-domain.com

# Database (PostgreSQL)
POSTGRES_HOST=localhost
POSTGRES_PORT=5432
POSTGRES_USER=posthoot_user
POSTGRES_PASSWORD=your_secure_password
POSTGRES_DB=posthoot
POSTGRES_SSLMODE=disable

# Security
JWT_SECRET=your_very_long_and_secure_jwt_secret_key_here

# Storage
STORAGE_PROVIDER=local
STORAGE_BASE_PATH=./storage

# Workers (for processing emails)
WORKER_CONCURRENCY=5
WORKER_QUEUE_SIZE=100

# Redis (for caching and rate limiting)
REDIS_HOST=localhost
REDIS_PORT=6379
REDIS_PASSWORD=your_redis_password
REDIS_DB=0

# Admin account (created on first run)
SUPERADMIN_EMAIL=admin@yourdomain.com
SUPERADMIN_PASSWORD=secure_admin_password
SUPERADMIN_NAME=Admin

# SMTP (for sending emails)
SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_USER=your-email@gmail.com
SMTP_PASSWORD=your-app-password
SMTP_FROM_EMAIL=noreply@yourdomain.com
SMTP_PROVIDER=GMAIL

# Optional: S3 for file storage
S3_BUCKET_NAME=your-bucket-name
S3_ENDPOINT=https://s3.amazonaws.com
S3_REGION=us-east-1
S3_ACCESS_KEY=your-access-key
S3_SECRET_KEY=your-secret-key

# Optional: Dodo Payments for subscriptions
DODO_API_KEY=your_dodo_api_key
DODO_WEBHOOK_SECRET=your_dodo_webhook_secret

3. Set up the database

Create your PostgreSQL database:

# Connect to PostgreSQL
sudo -u postgres psql

# Create database and user
CREATE DATABASE posthoot;
CREATE USER posthoot_user WITH PASSWORD 'your_secure_password';
GRANT ALL PRIVILEGES ON DATABASE posthoot TO posthoot_user;
\q

4. Install Redis

Install and start Redis (pick your OS):

# Ubuntu/Debian
sudo apt update
sudo apt install redis-server
sudo systemctl enable redis-server
sudo systemctl start redis-server

# macOS
brew install redis
brew services start redis

# CentOS/RHEL
sudo yum install redis
sudo systemctl enable redis
sudo systemctl start redis

5. Get the dependencies

go mod download

6. Start the server

go run cmd/server/main.go

That’s it! Your server should be running on http://localhost:8080 (or whatever you configured).

Production Deployment Options

For production deployments, we offer several options depending on your infrastructure and requirements:

🐳 Docker Deployment (Recommended)

The easiest way to deploy with containerization. Perfect for most users.

Quick setup with Docker Compose
Isolated environments for each component
Easy scaling and management
Consistent deployments across environments

Prebuilt container images You can pull ready-to-run images from GitHub Container Registry:
# Next.js client (app)
docker pull ghcr.io/posthoot/posthoot-app.ts:latest

# Go backend API (server)
docker pull ghcr.io/posthoot/posthoot-backend.go:latest
Use these images directly in your Docker Compose / Kubernetes manifests for faster deployments.

View Docker Deployment Guide →

🚀 Kubernetes Deployment

Enterprise-grade deployment for high availability and scalability.

Multi-replica deployments with load balancing
Automatic scaling based on demand
Advanced monitoring and health checks
Production-grade security and networking

View Kubernetes Deployment Guide →

⚙️ Systemd Deployment

Native Linux service deployment for traditional server setups.

System service integration with automatic startup
Resource management and security features
Traditional server administration
Direct system integration

View Systemd Deployment Guide →

📊 PM2 Deployment

Node.js-style process management for Go applications.

Process clustering and load balancing
Zero-downtime deployments
Built-in monitoring and logging
Familiar for Node.js developers

Choose the deployment method that best fits your infrastructure and team expertise.

Configuration

Environment variables

Here are the main settings you can configure:

Variable	What it does	Default	Required?
`SERVER_HOST`	Where to bind the server	`localhost`	No
`SERVER_PORT`	Port to run on	`8080`	No
`PUBLIC_URL`	Your public URL	`http://localhost:8080`	No
`POSTGRES_HOST`	Database host	`localhost`	Yes
`POSTGRES_PORT`	Database port	`5432`	No
`POSTGRES_USER`	Database username	-	Yes
`POSTGRES_PASSWORD`	Database password	-	Yes
`POSTGRES_DB`	Database name	`posthoot`	No
`JWT_SECRET`	Secret for signing tokens	-	Yes
`REDIS_HOST`	Redis host	`localhost`	No
`REDIS_PORT`	Redis port	`6379`	No
`REDIS_PASSWORD`	Redis password	-	No
`SUPERADMIN_EMAIL`	Admin email	-	Yes (first run)
`SUPERADMIN_PASSWORD`	Admin password	-	Yes (first run)

Storage Options

Local Storage

STORAGE_PROVIDER=local
STORAGE_BASE_PATH=./storage

S3 Storage

STORAGE_PROVIDER=s3
S3_BUCKET_NAME=your-bucket
S3_ENDPOINT=https://s3.amazonaws.com
S3_REGION=us-east-1
S3_ACCESS_KEY=your-key
S3_SECRET_KEY=your-secret

SMTP Configuration

Gmail

SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_USER=your-email@gmail.com
SMTP_PASSWORD=your-app-password
SMTP_PROVIDER=GMAIL

SendGrid

SMTP_HOST=smtp.sendgrid.net
SMTP_PORT=587
SMTP_USER=apikey
SMTP_PASSWORD=your-sendgrid-api-key
SMTP_PROVIDER=SENDGRID

Security Considerations

Basic Security Setup

For production deployments, consider these essential security measures:

Firewall configuration - Restrict access to necessary ports only
Reverse proxy setup - Use Nginx or Apache for SSL termination
SSL certificates - Install Let’s Encrypt or commercial certificates
Database security - Create read-only users for backups
Regular updates - Keep system and dependencies updated

Each deployment guide includes detailed security configurations specific to that method:

Monitoring and Logging

Essential Monitoring

For production deployments, implement these monitoring components:

Health checks - Use the /health endpoint for service monitoring
Application logs - Configure log rotation and aggregation
Metrics collection - Set up Prometheus and Grafana
Alerting - Configure alerts for critical issues

Each deployment guide includes specific monitoring setup:

Health Check Endpoint

The application provides a health check endpoint:

curl http://localhost:9001/health

Expected response:

{
  "status": "healthy",
  "version": "1.0.0",
  "time": "2024-01-01T12:00:00Z"
}

Backup Strategy

Essential Backup Components

For production deployments, implement these backup strategies:

Database backups - Regular PostgreSQL dumps with compression
File storage backups - Backup application data and uploads
Configuration backups - Backup environment files and settings
Automated scheduling - Use cron jobs for regular backups

Each deployment guide includes specific backup procedures:

Basic Database Backup

# Create backup
pg_dump -h localhost -U posthoot_user -d posthoot > backup.sql

# Restore backup
psql -h localhost -U posthoot_user -d posthoot < backup.sql

Troubleshooting

Common Issues

For detailed troubleshooting guides specific to each deployment method:

Basic Debugging Commands

# Check service status
systemctl status posthoot

# View logs
journalctl -u posthoot -f

# Test database connection
psql -h localhost -U posthoot_user -d posthoot

# Test Redis connection
redis-cli ping

# Check port usage
netstat -tlnp | grep :9001

Performance Tuning

Optimization Areas

For production deployments, consider these performance optimizations:

Database tuning - Index optimization and query performance
Redis configuration - Memory management and persistence
Application settings - Worker concurrency and connection pooling
System resources - CPU, memory, and network optimization

Each deployment guide includes specific performance tuning:

Basic Database Optimization

-- Analyze table statistics
ANALYZE;

-- Create indexes for frequently queried columns
CREATE INDEX idx_users_email ON users(email);
CREATE INDEX idx_campaigns_status ON campaigns(status);
CREATE INDEX idx_emails_sent_at ON emails(sent_at);

Support

If you encounter issues while self-hosting:

Check the logs for error messages
Review this documentation for common solutions
Search existing issues on GitHub
Create a new issue with detailed information including:
- Your environment (OS, Go version, etc.)
- Configuration (sanitized)
- Error logs
- Steps to reproduce

Kubernetes Deployment

For production environments, we recommend using Kubernetes for better scalability, reliability, and management. We’ve created a comprehensive Kubernetes setup that includes all necessary components.

Prerequisites

Kubernetes cluster (v1.20+)
kubectl configured to access your cluster
Docker registry access
NGINX Ingress Controller installed
cert-manager installed (for SSL certificates)

Quick Deployment

Navigate to the Kubernetes directory:

cd server/k8s

Update configuration:
- Edit secret.yaml with your actual passwords and keys
- Update configmap.yaml for non-sensitive configuration
- Modify ingress.yaml with your domain name
Build and deploy:

# Make the deployment script executable
chmod +x deploy.sh

# Deploy everything
./deploy.sh --registry your-registry --tag latest

Architecture Overview

The Kubernetes setup includes:

Namespace: posthoot-server for isolation
Database: PostgreSQL with persistent storage (10Gi)
Cache: Redis with persistent storage (5Gi)
Application: Posthoot server (2 replicas with HPA)
Monitoring: Asynqmon for background job monitoring
Networking: Ingress with SSL termination
Security: Network policies and proper RBAC

Key Features

High Availability

Multiple server replicas with load balancing
Persistent storage for database and cache
Health checks and automatic recovery
Horizontal Pod Autoscaler (2-10 replicas)

Security

Network policies restricting pod communication
Secrets management for sensitive data
SSL termination with automatic certificate renewal
Isolated namespace

Monitoring

Health check endpoints (/health)
Asynqmon dashboard for background jobs
Resource monitoring and alerting
Comprehensive logging

Scaling

Automatic scaling based on CPU/memory usage
Resource limits and requests
Connection pooling optimization
Background job processing

Configuration

Environment Variables

All environment variables are managed through ConfigMaps and Secrets:

# Non-sensitive configuration (configmap.yaml)
SERVER_HOST: "0.0.0.0"
SERVER_PORT: "9001"
DB_HOST: "posthoot-postgres"
REDIS_HOST: "posthoot-redis"

# Sensitive configuration (secret.yaml)
POSTGRES_PASSWORD: "base64-encoded-password"
JWT_SECRET: "base64-encoded-jwt-secret"

Resource Allocation

PostgreSQL: 256Mi-512Mi RAM, 250m-500m CPU
Redis: 128Mi-256Mi RAM, 100m-200m CPU
Server: 512Mi-1Gi RAM, 500m-1000m CPU
Asynqmon: 128Mi-256Mi RAM, 100m-200m CPU

Management Commands

Check Status

# View all resources
kubectl get all -n posthoot-server

# Check pod status
kubectl get pods -n posthoot-server

# View logs
kubectl logs -n posthoot-server deployment/posthoot-server

Scaling

# Scale server replicas
kubectl scale deployment posthoot-server --replicas=5 -n posthoot-server

# Check HPA status
kubectl get hpa -n posthoot-server

Updates

# Update image
kubectl set image deployment/posthoot-server posthoot-server=your-registry/posthoot-server:v1.1.0 -n posthoot-server

# Monitor rollout
kubectl rollout status deployment/posthoot-server -n posthoot-server

Backup

# Database backup
kubectl exec -n posthoot-server deployment/posthoot-postgres -- pg_dump -U posthoot posthoot > backup.sql

# Restore backup
kubectl exec -n posthoot-server deployment/posthoot-postgres -- psql -U posthoot posthoot < backup.sql

Troubleshooting

Common Issues

Image Pull Errors

# Check image availability
kubectl describe pod -n posthoot-server <pod-name>

Database Connection Issues

# Check PostgreSQL logs
kubectl logs -n posthoot-server deployment/posthoot-postgres

Ingress Issues

# Check ingress status
kubectl get ingress -n posthoot-server
kubectl describe ingress posthoot-ingress -n posthoot-server

Debugging

# Port forward for local access
kubectl port-forward -n posthoot-server svc/posthoot-server 9001:80

# Access Asynqmon dashboard
kubectl port-forward -n posthoot-server svc/posthoot-asynqmon 8080:8080

Production Considerations

Monitoring Setup

Install Prometheus and Grafana for metrics
Set up alerting for critical issues
Configure log aggregation (ELK stack)

Backup Strategy

Regular database backups with retention policy
Persistent volume snapshots
Disaster recovery testing

Security Hardening

Network policies for pod isolation
RBAC with least privilege access
Regular security updates
Secrets rotation

For detailed Kubernetes configuration and advanced setup options, see the Kubernetes README.

Next Steps

After successfully setting up your self-hosted instance:

Configure your frontend to point to your API
Set up monitoring and alerting
Configure backups and test restore procedures
Review security settings and update regularly
Join the community for updates and support

​Self-Hosting Guide

​What you’ll need

​Server specs

​Quick Start

​1. Get the code

​2. Set up your environment

​3. Set up the database

​4. Install Redis

​5. Get the dependencies

​6. Start the server

​Production Deployment Options

​🐳 Docker Deployment (Recommended)

​🚀 Kubernetes Deployment

​⚙️ Systemd Deployment

​📊 PM2 Deployment

​Configuration

​Environment variables

​Storage Options

​Local Storage

​S3 Storage

​SMTP Configuration

​Gmail

​SendGrid

​Security Considerations

​Basic Security Setup

​Monitoring and Logging

​Essential Monitoring

​Health Check Endpoint

​Backup Strategy

​Essential Backup Components

​Basic Database Backup

​Troubleshooting

​Common Issues

​Basic Debugging Commands

​Performance Tuning

​Optimization Areas

​Basic Database Optimization

​Support

​Kubernetes Deployment

​Prerequisites

​Quick Deployment

​Architecture Overview

​Key Features

​High Availability

​Security

​Monitoring

​Scaling

​Configuration

​Environment Variables

​Resource Allocation

​Management Commands

​Check Status

​Scaling

​Updates

​Backup

​Troubleshooting

​Common Issues

​Debugging

​Production Considerations

​Monitoring Setup

​Backup Strategy

​Security Hardening

​Next Steps

Self-Hosting Guide

What you’ll need

Server specs

Quick Start

1. Get the code

2. Set up your environment

3. Set up the database

4. Install Redis

5. Get the dependencies

6. Start the server

Production Deployment Options

🐳 Docker Deployment (Recommended)

🚀 Kubernetes Deployment

⚙️ Systemd Deployment

📊 PM2 Deployment

Configuration

Environment variables

Storage Options

Local Storage

S3 Storage

SMTP Configuration

Gmail

SendGrid

Security Considerations

Basic Security Setup

Monitoring and Logging

Essential Monitoring

Health Check Endpoint

Backup Strategy

Essential Backup Components

Basic Database Backup

Troubleshooting

Common Issues

Basic Debugging Commands

Performance Tuning

Optimization Areas

Basic Database Optimization

Support

Kubernetes Deployment

Prerequisites

Quick Deployment

Architecture Overview

Key Features

High Availability

Security

Monitoring

Scaling

Configuration

Environment Variables

Resource Allocation

Management Commands

Check Status

Scaling

Updates

Backup

Troubleshooting

Common Issues

Debugging

Production Considerations

Monitoring Setup

Backup Strategy

Security Hardening

Next Steps