Documentation

Self-Hosting
Setup Guide

Everything you need to install and run BareStack on your own server — Ubuntu, Docker, or cloud VPS.

Quick Start

Get BareStack running in under 5 minutes with Docker. If you already have a server with Docker installed, run:

bash

# Clone the repository
git clone https://github.com/anirudhprashant/barestack-app.git
cd barestack-app

# Start with Docker
docker compose up -d

# Open in browser
open http://localhost:3000

Default login: [email protected] / admin123. Change this immediately in settings after first login.

Installation

BareStack supports two installation methods: Docker (recommended for most users) or manual setup on Ubuntu 22.04+.

System Requirements

Ubuntu 22.04 LTS (fresh install recommended)
2 GB RAM minimum (4 GB recommended)
20 GB disk space
Docker & Docker Compose v2
Domain pointing to server (optional, for production)

Install Docker on Ubuntu

bash

sudo apt update && sudo apt upgrade -y
sudo apt install -y docker.io docker-compose-v2
sudo systemctl enable docker
sudo usermod -aG docker $USER
newgrp docker

Clone and Configure

bash

git clone https://github.com/anirudhprashant/barestack-app.git
cd barestack-app
cp .env.example .env
nano .env  # Edit your environment variables

Edit the .env file with your database password, domain name, and secrets.

Start BareStack

bash

docker compose up -d
docker compose ps  # Check status
docker compose logs -f  # View logs

Configuration

All configuration is done via environment variables in the .env file. Restart the containers after changing variables.

bash

# Core Settings
APP_URL=https://your-domain.com
APP_PORT=3000
NODE_ENV=production

# Database
DB_HOST=localhost
DB_PORT=5432
DB_NAME=barestack
DB_USER=barestack
DB_PASSWORD=your_secure_password_here

# Authentication
JWT_SECRET=your_jwt_secret_min_32_chars
SESSION_SECRET=your_session_secret

# Email (SMTP)
SMTP_HOST=smtp.example.com
SMTP_PORT=587
[email protected]
SMTP_PASSWORD=your_smtp_password
SMTP_FROM="BareStack" <[email protected]>

# File Storage
STORAGE_TYPE=local  # or 's3'
S3_BUCKET=barestack-uploads
S3_REGION=eu-west-1
AWS_ACCESS_KEY_ID=your_aws_key
AWS_SECRET_ACCESS_KEY=your_aws_secret

Cloud Setup

Deploy BareStack to any cloud provider. We recommend Hetzner, DigitalOcean, or AWS for self-hosting.

Hetzner Cloud (Recommended)

bash

# Create a new server (CX22 = 4 GB RAM, 40 GB NVMe, ~€5/mo)
hcloud server create --name barestack --location nbg1 \
  --image ubuntu-22.04 --type cx22

# Point your domain A record to the server IP
# Install Docker and BareStack as per Installation guide

Set Up Nginx Reverse Proxy

bash

sudo apt install -y nginx certbot python3-certbot-nginx

sudo nano /etc/nginx/sites-available/barestack

nginx

server {
    listen 80;
    server_name your-domain.com;

    location / {
        proxy_pass http://localhost:3000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_cache_bypass $http_upgrade;
    }
}

bash

sudo ln -s /etc/nginx/sites-available/barestack /etc/nginx/sites-enabled/
sudo nginx -t
sudo certbot --nginx -d your-domain.com
sudo systemctl reload nginx

Set Up Firewall

bash

sudo ufw default deny incoming
sudo ufw default allow outgoing
sudo ufw allow ssh
sudo ufw allow http
sudo ufw allow https
sudo ufw enable

Enable Auto-Restart

bash

sudo systemctl enable docker
sudo systemctl enable nginx
# Add to crontab for automatic updates
sudo crontab -e

bash

# Add this line for weekly security updates
0 3 * * 0 apt update && apt upgrade -y && docker compose -C /path/to/barestack-app restart

Tech Stack

BareStack is built with modern, battle-tested open-source technologies. No vendor lock-in. No subscriptions for the core software.

Next.js 15

App Router frontend

Node.js

API server runtime

TypeScript

Type-safe throughout

Tailwind CSS

Utility-first styling

PostgreSQL 16

Primary relational database

Prisma ORM

Database access layer

NextAuth.js

Authentication

Redis

Caching and sessions

Docker

Containerised deployment

Nginx

Reverse proxy + SSL

Supabase / Postgres

Optional cloud database

Cloudflare

DNS + CDN + security

Troubleshooting

Common issues and how to resolve them. If your problem is not listed here, open an issue on GitHub.

1. Docker container keeps restarting

Check logs with docker compose logs -f to identify the error. Common causes:

bash

docker compose logs app
# Look for error messages at the bottom
# Usually: wrong environment variables or port already in use

# Fix port conflict
sudo lsof -i :3000
# Kill the process or change APP_PORT in .env

2. Cannot connect to database

The database container may not be ready when the app starts, or credentials are wrong.

bash

# Check if Postgres is running
docker compose ps db

# Check Postgres logs
docker compose logs db

# Try restarting in order
docker compose stop app
docker compose start db
sleep 5
docker compose start app

3. Email not sending

Verify your SMTP settings and check if your email provider allows SMTP relay.

bash

# Test SMTP connection
docker compose exec app telnet smtp.yourprovider.com 587

# Check email logs
docker compose logs app | grep -i smtp

# Common fix: use an app password instead of your real password
# Gmail: Enable 2FA, then generate an App Password
SMTP_PASSWORD=your_app_password_here

4. Slow performance on first load

This is normal for the first request as Next.js builds the pages. Subsequent loads will be fast.

bash

# For production, pre-build pages
docker compose exec app npm run build

# Or use PM2 for process management
npm install -g pm2
pm2 start npm --name "barestack" -- start

# Enable Redis caching for sessions
REDIS_URL=redis://localhost:6379

5. SSL certificate not renewing

Certbot may need to be run manually or the nginx container may not have the correct configuration.

bash

# Force renew SSL certificate
sudo certbot --nginx -d your-domain.com --force-renewal

# Or use Let's Encrypt directly
sudo certbot certonly --nginx -d your-domain.com

# Check renewal timer
sudo systemctl status certbot.timer

Still stuck after reading the docs?

A 20-minute call can get you unblocked in minutes. No sales pitch, just practical help.

More answers in the FAQ, or compare BareStack against other tools and hosting stacks.

Self-HostingSetup Guide

Quick Start

Installation

System Requirements

Install Docker on Ubuntu

Clone and Configure

Start BareStack

Configuration

Cloud Setup

Hetzner Cloud (Recommended)

Set Up Nginx Reverse Proxy

Set Up Firewall

Enable Auto-Restart

Tech Stack

Troubleshooting

Self-Hosting
Setup Guide