Tinyauth Deployment and Usage Guide

1. Prerequisites

Runtime & Tools

Go 1.21+ (for building from source)
Docker & Docker Compose (for containerized deployment)
SQLite (embedded, no separate installation needed)
Git (for cloning the repository)

Accounts (Optional for OAuth)

Google OAuth credentials (if using Google login)
GitHub OAuth credentials (if using GitHub login)
LDAP/Active Directory server (if using enterprise authentication)

System Requirements

Linux, macOS, or Windows (with WSL2 for Windows)
Minimum 512MB RAM
100MB disk space

2. Installation

Using Docker (Recommended)

# Pull the latest image
docker pull ghcr.io/steveiliop56/tinyauth:latest

# Or using docker-compose with the example file
git clone https://github.com/steveiliop56/tinyauth.git
cd tinyauth
docker-compose -f docker-compose.example.yml up -d

From Source

# Clone the repository
git clone https://github.com/steveiliop56/tinyauth.git
cd tinyauth

# Build the binary
go build -o tinyauth ./cmd/tinyauth

# Make it executable
chmod +x tinyauth

Using Go Install

go install github.com/steveiliop56/tinyauth/cmd/tinyauth@latest

3. Configuration

Configuration File

Create a config.yaml file (or use environment variables):

appUrl: "https://auth.yourdomain.com"
resourcesDir: "./resources"
databasePath: "./tinyauth.db"
disableAnalytics: false

server:
  port: 3000
  address: "0.0.0.0"

auth:
  sessionExpiry: 86400  # 1 day in seconds
  sessionMaxLifetime: 0 # disabled
  loginTimeout: 300     # 5 minutes
  loginMaxRetries: 3
  secureCookie: true
  cookieDomain: ".yourdomain.com"
  sessionCookieName: "tinyauth-session"
  
  users:
    - username: "admin"
      password: "$2a$10$..."  # bcrypt hash
      groups: ["admin"]
    - username: "user"
      password: "$2a$10$..."
      groups: ["user"]

ui:
  title: "Tinyauth"
  forgotPasswordMessage: "Contact your administrator"
  backgroundImage: "/background.jpg"

ldap:
  enabled: false
  url: "ldap://ldap.example.com:389"
  bindDN: "cn=admin,dc=example,dc=com"
  bindPassword: "password"
  userSearchBase: "ou=users,dc=example,dc=com"
  userSearchFilter: "(uid=%s)"
  groupSearchBase: "ou=groups,dc=example,dc=com"
  groupSearchFilter: "(memberUid=%s)"
  insecure: false
  groupCacheTTL: 900  # 15 minutes

oidc:
  enabled: true
  privateKeyPath: "./tinyauth_oidc_key"
  publicKeyPath: "./tinyauth_oidc_key.pub"
  clients:
    - clientId: "your-app-client-id"
      clientSecret: "your-app-client-secret"
      redirectUris: ["https://app.yourdomain.com/oidc/callback"]
      scopes: ["openid", "profile", "email"]

log:
  level: "info"
  json: false
  streams:
    http:
      enabled: true
      level: "info"
    app:
      enabled: true
      level: "info"
    audit:
      enabled: false
      level: "info"

Environment Variables

All configuration options can be set via environment variables (uppercase with underscores):

export APP_URL="https://auth.yourdomain.com"
export SERVER_PORT=3000
export AUTH_SESSION_EXPIRY=86400
export LDAP_URL="ldap://ldap.example.com:389"
export OIDC_ENABLED=true

Generate Password Hash

# Using the tinyauth CLI
./tinyauth hash-password "yourpassword"

# Or using Python
python3 -c "import bcrypt; print(bcrypt.hashpw('yourpassword'.encode(), bcrypt.gensalt()).decode())"

OIDC Key Generation

Tinyauth will automatically generate OIDC keys on first run, or you can generate them manually:

openssl genrsa -out tinyauth_oidc_key 2048
openssl rsa -in tinyauth_oidc_key -pubout -out tinyauth_oidc_key.pub

4. Build & Run

Development Mode

# Clone and setup
git clone https://github.com/steveiliop56/tinyauth.git
cd tinyauth

# Install dependencies
go mod download

# Run with hot reload (install air first: go install github.com/cosmtrek/air@latest)
air

# Or run directly
go run ./cmd/tinyauth --config ./config.yaml

Production Build

# Build optimized binary
CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -ldflags="-w -s" -o tinyauth ./cmd/tinyauth

# Run with config
./tinyauth --config /path/to/config.yaml

# Or using systemd service
sudo cp tinyauth /usr/local/bin/
sudo cp tinyauth.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable tinyauth
sudo systemctl start tinyauth

Docker Build

# Build custom image
docker build -t tinyauth:latest .

# Run with mounted config
docker run -d \
  -p 3000:3000 \
  -v ./config.yaml:/app/config.yaml \
  -v ./data:/app/data \
  --name tinyauth \
  tinyauth:latest

5. Deployment

Docker Compose (Recommended)

# docker-compose.yml
version: '3.8'

services:
  tinyauth:
    image: ghcr.io/steveiliop56/tinyauth:latest
    container_name: tinyauth
    restart: unless-stopped
    ports:
      - "3000:3000"
    volumes:
      - ./config.yaml:/app/config.yaml
      - ./data:/app/data
      - ./resources:/app/resources
    environment:
      - APP_URL=https://auth.yourdomain.com
      - SERVER_PORT=3000

Kubernetes

# tinyauth-deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: tinyauth
spec:
  replicas: 1
  selector:
    matchLabels:
      app: tinyauth
  template:
    metadata:
      labels:
        app: tinyauth
    spec:
      containers:
      - name: tinyauth
        image: ghcr.io/steveiliop56/tinyauth:latest
        ports:
        - containerPort: 3000
        volumeMounts:
        - name: config
          mountPath: /app/config.yaml
          subPath: config.yaml
        - name: data
          mountPath: /app/data
        env:
        - name: APP_URL
          value: "https://auth.yourdomain.com"
      volumes:
      - name: config
        configMap:
          name: tinyauth-config
      - name: data
        persistentVolumeClaim:
          claimName: tinyauth-data

Reverse Proxy Setup

Nginx

server {
    listen 80;
    server_name auth.yourdomain.com;
    
    location / {
        proxy_pass http://localhost:3000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

Traefik (using Docker labels)

# docker-compose.yml
services:
  tinyauth:
    image: ghcr.io/steveiliop56/tinyauth:latest
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.tinyauth.rule=Host(`auth.yourdomain.com`)"
      - "traefik.http.routers.tinyauth.entrypoints=websecure"
      - "traefik.http.routers.tinyauth.tls.certresolver=letsencrypt"
    volumes:
      - ./config.yaml:/app/config.yaml

Caddy

auth.yourdomain.com {
    reverse_proxy localhost:3000
}

Platform Recommendations

Self-hosted: Docker on any VPS (DigitalOcean, Linode, AWS EC2)
Kubernetes: For scalable deployments
Cloud: AWS ECS, Google Cloud Run, Azure Container Instances
Home Lab: Perfect for protecting internal services

6. Troubleshooting

Common Issues

1. Database Errors

# Check database permissions
chmod 644 tinyauth.db
chown $(whoami):$(whoami) tinyauth.db

# Reset database (WARNING: deletes all data)
rm tinyauth.db
./tinyauth --init-db

2. Login Issues

"Invalid credentials": Check password hashes in config
"Account locked": Wait for login timeout (default 5 minutes) or increase loginMaxRetries
LDAP authentication fails: Verify LDAP server connectivity and credentials

3. Session Problems

Sessions not persisting: Ensure cookieDomain is set correctly for subdomains
Secure cookie errors: Set secureCookie: false for HTTP development

4. OIDC Issues

# Regenerate OIDC keys
rm tinyauth_oidc_key tinyauth_oidc_key.pub
./tinyauth --generate-keys

# Verify OIDC client configuration
# Check client ID, secret, and redirect URIs match exactly

5. Port Already in Use

# Check what's using port 3000
sudo lsof -i :3000

# Kill the process or change port in config
server:
  port: 3001  # Use different port

6. Permission Denied

# For Docker deployments
docker logs tinyauth --tail 50

# Check volume permissions
chmod -R 755 ./data
chmod -R 755 ./resources

7. LDAP Cache Issues

# Clear LDAP groups cache by restarting or
# Reduce cache TLD in config:
ldap:
  groupCacheTTL: 300  # 5 minutes instead of 15

Logging

Enable debug logging to diagnose issues:

log:
  level: "debug"
  json: true
  streams:
    http:
      enabled: true
      level: "debug"
    app:
      enabled: true
      level: "debug"

Check logs:

# Docker
docker logs tinyauth -f

# Systemd
journalctl -u tinyauth -f

# Binary
./tinyauth --config config.yaml 2>&1 | tee tinyauth.log

Health Check

# Check if service is running
curl http://localhost:3000/health

# Check OIDC discovery endpoint
curl http://localhost:3000/.well-known/openid-configuration

Getting Help

Check the official documentation
Visit the Discord server
Review GitHub issues
Try the demo (user/password)

How to Deploy & Use tinyauth