Skip to main content

​
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:

​
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: 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:
VariableWhat it doesDefaultRequired?
SERVER_HOSTWhere to bind the serverlocalhostNo
SERVER_PORTPort to run on8080No
PUBLIC_URLYour public URLhttp://localhost:8080No
POSTGRES_HOSTDatabase hostlocalhostYes
POSTGRES_PORTDatabase port5432No
POSTGRES_USERDatabase username-Yes
POSTGRES_PASSWORDDatabase password-Yes
POSTGRES_DBDatabase nameposthootNo
JWT_SECRETSecret for signing tokens-Yes
REDIS_HOSTRedis hostlocalhostNo
REDIS_PORTRedis port6379No
REDIS_PASSWORDRedis password-No
SUPERADMIN_EMAILAdmin email-Yes (first run)
SUPERADMIN_PASSWORDAdmin 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:
  1. Check the logs for error messages
  2. Review this documentation for common solutions
  3. Search existing issues on GitHub
  4. 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

  1. Navigate to the Kubernetes directory:
cd server/k8s
  1. 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
  2. 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

  1. Image Pull Errors 
    # Check image availability
kubectl describe pod -n posthoot-server <pod-name>
  2. Database Connection Issues 
    # Check PostgreSQL logs
kubectl logs -n posthoot-server deployment/posthoot-postgres
  3. 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:
  1. Configure your frontend to point to your API
  2. Set up monitoring and alerting
  3. Configure backups and test restore procedures
  4. Review security settings and update regularly
  5. Join the community for updates and support