Skip to content
✨ Olgax POS v0.1 MVP is live. Free and open-source!Star on GitHub →
OlgaxOlgax
tutorialself-hostingdockerdeployment

How to Self-Host Olgax POS with Docker

A step-by-step guide to deploying Olgax POS on your own server using Docker and Docker Compose, including SSL setup, domain configuration, and printer connectivity.

O

Olgax Team

March 15, 2026 · 3 min read

So you want to run your own POS system. Great choice. This guide walks you through deploying Olgax POS on a Linux VPS (we'll use Ubuntu 22.04) or on your local machine.

Prerequisites

  • A server (VPS) with at least 1 GB RAM (DigitalOcean, Hetzner, Linode, or similar)
  • Docker and Docker Compose installed
  • A domain name (optional but recommended for production)
  • 15 minutes

Step 1: Install Docker

If you don't have Docker yet:

curl -fsSL https://get.docker.com | sh
sudo usermod -aG docker $USER
newgrp docker

Verify:

docker --version
docker compose version

Step 2: Clone the Repository

git clone https://github.com/OLGAX-com/olgax-pos.git
cd olgax-pos

Step 3: Configure Environment Variables

cp .env.example .env
nano .env

Key variables to update:

# Database
DATABASE_URL=postgresql://olgax:changeme@postgres:5432/olgaxpos

# Auth secret (generate with: openssl rand -base64 32)
BETTER_AUTH_SECRET=your-secret-here
BETTER_AUTH_URL=https://yourdomain.com

# App URL
NEXT_PUBLIC_APP_URL=https://yourdomain.com

# Admin user (created on first run)
ADMIN_EMAIL=admin@yourshop.com
ADMIN_PASSWORD=changeme

Important: Always change the default passwords before going live.

Step 4: Start the Stack

docker compose up -d

This starts:

  • olgax-pos: the Next.js app on port 3000
  • postgres: PostgreSQL database
  • nginx: reverse proxy (handles SSL if you configure it)

Check that everything is running:

docker compose ps
docker compose logs -f olgax-pos

Step 5: Set Up SSL with Nginx (Production)

For a real deployment, you'll want HTTPS. The easiest way is with Caddy:

Create a Caddyfile in the project root:

yourdomain.com {
  reverse_proxy localhost:3000
}

And run Caddy:

caddy run

Caddy automatically handles SSL certificate issuance and renewal via Let's Encrypt.

Step 6: Configure Your Thermal Printer

Olgax POS supports ESC/POS thermal printers connected via:

  • USB: plug into the server, appear as /dev/usb/lp0
  • Network: connect printer to your LAN, note its IP address

In the Olgax POS admin panel, go to Settings → Printers and add your printer by its IP or USB path.

Popular supported models: Epson TM-T20, Epson TM-T88, Star TSP100, Sewoo, Bixolon.

Step 7: First Login

Open your browser at https://yourdomain.com (or http://localhost:3000 for local).

Log in with the admin credentials you set in .env. You'll be prompted to:

  1. Set up your business profile (name, currency, timezone)
  2. Add your first products / categories
  3. Configure tax rates
  4. Add staff accounts

You're live. 🎉

Updating to a New Version

git pull origin main
docker compose down
docker compose build
docker compose up -d

Database migrations run automatically on startup.

Troubleshooting

App won't start:

docker compose logs olgax-pos

Database connection errors: Make sure DATABASE_URL in .env matches the postgres service name in docker-compose.yml.

Printer not detected: Check USB permissions: sudo chmod 666 /dev/usb/lp0

Need Help?

tutorialself-hostingdockerdeployment