Quickstart Guide

Get ProjectSpecter up and running in minutes

Quickstart Guide

Get ProjectSpecter up and running in minutes.

Prerequisites

• Docker and Docker Compose installed
• SSH access to your VPS
• Domain registered and DNS configured in Cloudflare
• Descope account created

5-Minute Setup

Step 1: Clone and Configure

git clone <repository-url>
cd ProjectSpecter
cp .env.example .env

Step 2: Update Environment Variables

Edit .env with your configuration:

# Cloudflare
CF_API_EMAIL=[e-mail]
CF_DNS_API_TOKEN=your-cloudflare-token

# Descope
DESCOPE_PROJECT_ID=your-project-id
SESSION_SECRET=generate-random-secret

# Domain
PRIMARY_DOMAIN=your-domain.com

Step 3: Configure DNS in Cloudflare

Add these A records pointing to your VPS IP (e.g., 209.141.33.10):

A Record: @       → 209.141.33.10
A Record: traefik → 209.141.33.10
A Record: auth    → 209.141.33.10
A Record: *       → 209.141.33.10 (wildcard)

Step 4: Deploy Services

# SSH to your VPS
ssh root@your-vps-ip

# Navigate to project
cd /opt/ProjectSpecter

# Start services
docker compose up -d

# Verify services running
docker ps

Step 5: Access Your Services

• Traefik Dashboard: https://traefik.your-domain.com
• Login Page: https://auth.your-domain.com
• API: https://api.your-domain.com (once configured)

Verifying Installation

Check Container Status

docker ps --format "table {{.Names}}\t{{.Status}}"

Expected output:

NAMES              STATUS
traefik            Up X minutes
descope-auth       Up X minutes

Check Traefik Logs

docker logs traefik | tail -20

Look for messages indicating services are running and routes are registered.

Test HTTPS Connection

curl -I https://traefik.your-domain.com

Expected response:

HTTP/2 200

Adding Your First Service

To add a new application:

1. Create Service Definition

Add to your docker-compose.yml:

services:
  myapp:
    image: my-app:latest
    restart: unless-stopped
    networks:
      - traefik-proxy
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.myapp.rule=Host(`myapp.your-domain.com`)"
      - "traefik.http.routers.myapp.entrypoints=websecure"
      - "traefik.http.routers.myapp.tls.certresolver=cloudflare"
      - "traefik.http.services.myapp.loadbalancer.server.port=8080"
      # Add authentication (optional)
      - "traefik.http.routers.myapp.middlewares=descope-verify@docker"

networks:
  traefik-proxy:
    external: true

2. Deploy

docker compose up -d myapp

3. Access

https://myapp.your-domain.com

Common Commands

# Start all services
docker compose up -d

# Stop all services
docker compose down

# View logs
docker logs traefik -f
docker logs descope-auth -f

# Restart a service
docker compose restart traefik

# Check service status
docker ps

# View Traefik dashboard
# Visit: https://traefik.your-domain.com

Next Steps

• Read Architecture Overview to understand the system
• Follow Initial Setup Guide for detailed configuration
• Check Troubleshooting if issues arise
• Review Component Documentation for deep dives

Troubleshooting

Services won’t start

docker logs traefik
docker logs descope-auth

Can’t access dashboard

1. Verify DNS is updated: nslookup traefik.your-domain.com
2. Check containers running: docker ps
3. Check firewall: ports 80/443 must be open

SSL certificate not generating

1. Wait 5 minutes - Let’s Encrypt takes time
2. Check Traefik logs: docker logs traefik | grep -i acme
3. Verify Cloudflare API token is correct

Authentication not working

1. Check Descope service: docker logs descope-auth
2. Verify PROJECT_ID is correct
3. Ensure SESSION_SECRET is set

See Troubleshooting Guide for more help.

---

Time to Deploy: ~5 minutes Difficulty: ⭐ Easy Next: Architecture Overview