gotempsh/temps-platform-setup

Temps Platform Setup & Management

Complete guide for installing and managing the Temps self-hosted deployment platform.

Table of Contents

• Overview
• Installation Methods
• Quick Start
• CLI Setup
• Initial Configuration
• Platform Management
• DNS & TLS Setup
• Troubleshooting

---

Overview

Temps is a self-hosted deployment platform with built-in analytics, monitoring, and error tracking. It deploys any application from Git with zero configuration.

Key Features:

• Deploy frontend, backend, and static sites from Git
• Built-in analytics, funnels, session replay
• Error tracking (Sentry-compatible)
• Uptime monitoring
• Automatic TLS certificates via Let's Encrypt
• PostgreSQL, Redis, MongoDB, S3 service provisioning
• Container orchestration with Docker

Supported Languages:

• Frontend: React, Next.js, Vue, Svelte, Angular
• Backend: Node.js, Python, Go, Rust, Ruby, PHP
• Static: Hugo, Jekyll, Gatsby
• Custom: Any application with a Dockerfile

---

Installation Methods

Method 1: Install Script (Recommended)

# Download and install Temps binary
curl -fsSL https://temps.sh/deploy.sh | bash

# Reload shell configuration
source ~/.zshrc  # or ~/.bashrc for bash users

What it does:

• Downloads the latest Temps binary
• Installs to ~/.temps/bin/
• Adds to PATH in your shell configuration
• Verifies installation

Verify installation:

temps --version

Method 2: Docker Compose (Production)

For production deployments with PostgreSQL and Redis:

# Clone the repository
git clone https://github.com/gotempsh/temps.git
cd temps

# Start with Docker Compose
docker-compose up -d

Docker Compose includes:

• Temps application server
• PostgreSQL 18 + TimescaleDB
• Redis for caching
• Automatic health checks
• Volume persistence

Access the application:

• API: http://localhost:3000
• Console: http://localhost:8081

Method 3: From Source (Development)

# Prerequisites: Rust 1.70+, PostgreSQL, Bun
git clone https://github.com/gotempsh/temps.git
cd temps

# Build Rust backend
cargo build --release --bin temps

# Build web console (optional)
cd web
bun install
RSBUILD_OUTPUT_PATH=../crates/temps-cli/dist bun run build
cd ..

# Run migrations and start
./target/release/temps serve \
  --database-url "postgresql://user:pass@localhost:5432/temps"

---

Quick Start

1. Start PostgreSQL Database

Temps requires PostgreSQL 14+ with TimescaleDB extension.

Using Docker (easiest):

# Create persistent volume
docker volume create temps-postgres

# Start PostgreSQL + TimescaleDB
docker run -d \
  --name temps-postgres \
  -v temps-postgres:/home/postgres/pgdata/data \
  -e POSTGRES_USER=postgres \
  -e POSTGRES_PASSWORD=temps \
  -e POSTGRES_DB=temps \
  -p 16432:5432 \
  timescale/timescaledb-ha:pg18

Connection string:

postgresql://postgres:temps@localhost:16432/temps

2. Run Temps Setup

The setup command initializes the database, creates admin user, and configures DNS/TLS:

temps setup \
  --database-url "postgresql://postgres:temps@localhost:16432/temps" \
  --admin-email "[email protected]" \
  --wildcard-domain "*.yourdomain.com" \
  --github-token "ghp_xxxxxxxxxxxx" \
  --dns-provider "cloudflare" \
  --cloudflare-token "your-cloudflare-api-token"

Setup options:

| Option | Description | Required | |--------|-------------|----------| | --database-url | PostgreSQL connection string | ✅ Yes | | --admin-email | Admin user email | ✅ Yes | | --wildcard-domain | Domain for deployments (e.g., *.temps.sh) | Optional | | --github-token | GitHub personal access token | Optional | | --dns-provider | DNS provider (cloudflare, route53, digitalocean) | Optional | | --cloudflare-token | Cloudflare API token | If using Cloudflare | | --route53-access-key | AWS access key | If using Route53 | | --route53-secret-key | AWS secret key | If using Route53 |

What setup does:

1. Runs database migrations
2. Installs TimescaleDB extension
3. Creates admin user with API token
4. Configures DNS provider for automatic DNS records
5. Sets up Let's Encrypt ACME account for TLS certificates
6. Creates encryption keys for secure storage
7. Displays admin API token (save this!)

3. Start Temps Server

temps serve \
  --database-url "postgresql://postgres:temps@localhost:16432/temps" \
  --address 0.0.0.0:80 \
  --tls-address 0.0.0.0:443 \
  --console-address 0.0.0.0:8081

Server options:

| Option | Description | Default | Environment Variable | |--------|-------------|---------|---------------------| | --address | HTTP API address | 127.0.0.1:3000 | TEMPS_ADDRESS | | --tls-address | HTTPS address (proxy) | - | TEMPS_TLS_ADDRESS | | --console-address | Admin console address | - | TEMPS_CONSOLE_ADDRESS | | --database-url | PostgreSQL URL | - | TEMPS_DATABASE_URL | | --data-dir | Data directory | ~/.temps | TEMPS_DATA_DIR |

Access points:

• API: http://localhost:3000 or https://yourdomain.com
• Console: http://localhost:8081 (admin UI)
• Deployments: https://app-name.yourdomain.com (auto-generated)

4. Access the Console

Open the console in your browser:

# If running locally
open http://localhost:8081

# If running on server with domain
open https://temps.yourdomain.com

First login:

• Email: The email you provided during setup
• API Token: The token displayed after temps setup (check terminal output)

---

CLI Setup

The Temps CLI lets you manage projects, deployments, and services from the command line.

Installation

Option 1: Run without installing (recommended for CI/CD)

# Using npx
npx @temps-sdk/cli --version

# Using bunx (faster)
bunx @temps-sdk/cli --version

Option 2: Install globally

# Using npm
npm install -g @temps-sdk/cli

# Using bun
bun add -g @temps-sdk/cli

# Verify installation
temps --version

Authentication

Interactive login:

temps login

You'll be prompted for:

• API URL: Your Temps server URL (e.g., https://temps.yourdomain.com or http://localhost:3000)
• API Token: The token from temps setup output

Non-interactive login (CI/CD):

temps login --api-key tk_abc123def456 -u https://temps.yourdomain.com

Using environment variables:

# Set environment variables
export TEMPS_API_URL="https://temps.yourdomain.com"
export TEMPS_TOKEN="tk_abc123def456"

# Commands will use these automatically
temps projects list

Verify authentication:

temps whoami

Example output:

  Logged in as: [email protected]
  Role: Admin
  API URL: https://temps.yourdomain.com

Configuration

The CLI stores configuration in ~/.temps/:

# View current configuration
temps configure show

# Set API URL
temps configure set apiUrl https://temps.yourdomain.com

# Set output format (table, json, minimal)
temps configure set outputFormat table

# List all settings
temps configure list

# Reset to defaults
temps configure reset

Configuration files:

• Config: ~/.temps/config.json (API URL, output format)
• Credentials: ~/.temps/.secrets (API tokens, mode 0600)

Environment variables (override config):

| Variable | Description | |----------|-------------| | TEMPS_API_URL | Override API endpoint | | TEMPS_TOKEN | API token (highest priority) | | TEMPS_API_TOKEN | API token (CI/CD) | | TEMPS_API_KEY | API key | | NO_COLOR | Disable colored output |

---

Initial Configuration

Create Your First Project

# Create a project
temps projects create my-app

# Or interactively
temps projects create

You'll be prompted for:

• Project name
• Git provider (GitHub, GitLab, Bitbucket)
• Repository URL
• Main branch (default: main)

Connect Git Provider

To deploy from Git, connect a provider:

GitHub:

temps git-providers add github \
  --name "My GitHub" \
  --token "ghp_xxxxxxxxxxxx"

Get GitHub token:

1. Go to https://github.com/settings/tokens
2. Create a personal access token (classic)
3. Required scopes: repo, read:org

GitLab:

temps git-providers add gitlab \
  --name "My GitLab" \
  --token "glpat-xxxxxxxxxxxx" \
  --url "https://gitlab.com"  # or self-hosted URL

List providers:

temps git-providers list

Create Environment

Environments isolate deployments (production, staging, development):

# Create production environment
temps environments create production

# Create with resource limits
temps environments create staging \
  --cpu 0.5 \
  --memory 512Mi \
  --replicas-min 1 \
  --replicas-max 3

List environments:

temps environments list

Set Environment Variables

# Set a variable
temps env set DATABASE_URL="postgresql://..." \
  --environment production \
  --project my-app

# Set from .env file
temps env import .env \
  --environment production \
  --project my-app

# List variables
temps env list \
  --environment production \
  --project my-app

Secure secrets:

• All environment variables are encrypted at rest
• API keys and tokens are masked in UI
• Only the application runtime can decrypt values

---

Platform Management

User Management

Create additional admin users:

# Create user via CLI
temps users create \
  --email "[email protected]" \
  --role admin

# Or create via console UI
# Navigate to Settings → Users → Create User

User roles:

• Admin: Full platform access, can create users
• User: Can create projects and deploy applications
• Viewer: Read-only access

List users:

temps users list

API Keys & Tokens

Create API token:

temps tokens create \
  --name "CI/CD Token" \
  --expires-in 90d

Create API key:

temps api-keys create \
  --name "Production API Key" \
  --permissions deployments.read,deployments.create

List tokens:

temps tokens list

Service Provisioning

Temps can provision PostgreSQL, Redis, MongoDB, and S3 services:

PostgreSQL:

temps services create postgres \
  --name my-database \
  --version 16 \
  --storage 10Gi

Redis:

temps services create redis \
  --name my-cache \
  --version 7

S3 (MinIO):

temps services create s3 \
  --name my-storage \
  --storage 20Gi

List services:

temps services list

Connection strings:

Services automatically create connection strings available as environment variables:

• PostgreSQL: DATABASE_URL
• Redis: REDIS_URL
• S3: S3_ENDPOINT, S3_ACCESS_KEY, S3_SECRET_KEY, S3_BUCKET

Monitoring & Logs

View deployment logs:

# Stream logs
temps logs --deployment-id 123 --follow

# Show last 100 lines
temps logs --deployment-id 123 --tail 100

View container logs:

temps containers logs container-abc123 --follow

Monitor deployments:

# List deployments
temps deployments list --project my-app

# Show deployment status
temps deployments show 123

Backups

Create backup schedule:

temps backups create \
  --service postgres-123 \
  --schedule "0 2 * * *"  # Daily at 2 AM

Manual backup:

temps backups run --service postgres-123

List backups:

temps backups list --service postgres-123

Restore backup:

temps backups restore backup-456 \
  --target postgres-123

---

DNS & TLS Setup

DNS Providers

Temps supports automatic DNS record management:

Cloudflare:

temps dns-providers add cloudflare \
  --token "your-cloudflare-api-token" \
  --zone-id "your-zone-id"

AWS Route53:

temps dns-providers add route53 \
  --access-key-id "AKIAIOSFODNN7EXAMPLE" \
  --secret-access-key "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY" \
  --region "us-east-1"

DigitalOcean:

temps dns-providers add digitalocean \
  --token "dop_v1_xxxxxxxxxxxx"

List providers:

temps dns-providers list

Custom Domains

Add custom domain to project:

temps domains add example.com \
  --project my-app \
  --environment production

Add wildcard domain:

temps domains add "*.example.com" \
  --project my-app \
  --environment production

Verify DNS challenge (for TLS certificate):

temps domains verify example.com

What happens:

1. Temps creates DNS records via configured provider
2. Requests Let's Encrypt certificate via ACME
3. Completes DNS-01 challenge automatically
4. Issues certificate and configures TLS
5. Auto-renews 30 days before expiration

Check domain status:

temps domains list --project my-app

TLS Certificates

Certificate orders:

# List certificate orders
temps certificates list

# Show certificate details
temps certificates show cert-123

# Force renewal
temps certificates renew cert-123

Manual DNS challenge (if auto DNS fails):

# Start certificate order
temps domains add example.com --project my-app

# Get DNS challenge records
temps certificates challenge cert-123

# Add records manually to your DNS provider
# Then complete challenge
temps certificates complete cert-123

Self-hosted behind NAT/firewall with *.temps.dev subdomain:

If your Temps instance is behind NAT or a firewall and cannot receive HTTP-01 challenges on port 80, use acme.sh with @temps-sdk/cli cloud ACME commands for DNS-01 validation. This lets you provision TLS certificates for your *.temps.dev subdomain without exposing port 80. The flow uses temps cloud acme (from @temps-sdk/cli) to manage DNS records and temps domain import (server-side Rust binary) to load the certificate into Temps.

See the Cloud ACME Certificates (acme.sh) section in the Temps CLI reference for the complete setup guide, including the DNS hook script and step-by-step certificate flow.

---

Troubleshooting

Database Connection Issues

Error: Failed to connect to database

Solution:

# Verify PostgreSQL is running
docker ps | grep postgres

# Test connection
psql "postgresql://postgres:temps@localhost:16432/temps" -c "SELECT version();"

# Check database URL format
temps serve --database-url "postgresql://user:password@host:port/database"

Port Already in Use

Error: Address already in use (os error 48)

Solution:

# Find process using port 3000
lsof -i :3000

# Kill process
kill -9 <PID>

# Or use different port
temps serve --address 0.0.0.0:3001

TLS Certificate Issues

Error: Failed to obtain TLS certificate

Solutions:

1. Check DNS propagation:

# Verify DNS records exist
dig example.com
dig _acme-challenge.example.com TXT

2. Verify DNS provider credentials:

temps dns-providers list

3. Check rate limits:

   • Let's Encrypt: 50 certs per registered domain per week
   • Use staging environment for testing: --acme-staging

4. Manual DNS challenge:

# Get challenge record
temps certificates challenge cert-123

# Add TXT record manually
# _acme-challenge.example.com TXT "challenge-value"

# Complete after DNS propagation (60s+)
temps certificates complete cert-123

Deployment Failures

Error: Build failed

Debug steps:

1. Check build logs:

temps logs --deployment-id 123

2. Verify build command:

# Test locally
npm run build  # or your build command

3. Check environment variables:

temps env list --project my-app --environment production

4. Test Docker build locally:

docker build -t test-image .
docker run -p 3000:3000 test-image

Service Connection Issues

Error: Service postgres-123 not reachable

Solution:

# Check service status
temps services show postgres-123

# Verify service is running
temps containers list | grep postgres-123

# Check service logs
temps containers logs <container-id>

# Restart service
temps services restart postgres-123

CLI Authentication Issues

Error: Unauthorized (401)

Solution:

# Verify token is valid
temps whoami

# Re-login
temps logout
temps login

# Or use environment variable
export TEMPS_TOKEN="tk_your_token_here"
temps whoami

MaxMind GeoLite2 Database Missing

Error: GeoLite2-City.mmdb not found

Solution:

The analytics feature requires MaxMind GeoLite2 database for IP geolocation.

1. Download GeoLite2-City database:

   • Sign up at https://www.maxmind.com/en/geolite2/signup
   • Download GeoLite2-City database (GZIP format)

2. Extract and place:

# Extract
tar xzf GeoLite2-City_*.tar.gz

# Copy to Temps data directory
cp GeoLite2-City_*/GeoLite2-City.mmdb ~/.temps/

# Or specify custom path
temps serve --data-dir /path/to/data

3. Verify:

ls -lh ~/.temps/GeoLite2-City.mmdb

Note: Temps works without this database, but geolocation features will be disabled.

---

Quick Reference

Common Commands

# Platform
temps setup --database-url "postgres://..." --admin-email "[email protected]"
temps serve --database-url "postgres://..." --address 0.0.0.0:80

# CLI
temps login
temps projects list
temps deployments list

# Projects
temps projects create my-app
temps env set KEY=value --project my-app --environment production

# Services
temps services create postgres --name mydb --version 16
temps services list

# Domains
temps domains add example.com --project my-app
temps domains verify example.com

# Monitoring
temps logs --deployment-id 123 --follow
temps deployments show 123

Configuration Files

| File | Purpose | Location | |------|---------|----------| | config.json | CLI configuration | ~/.temps/config.json | | .secrets | API tokens | ~/.temps/.secrets | | encryption_key | Encryption key | ~/.temps/encryption_key | | GeoLite2-City.mmdb | Geolocation database | ~/.temps/GeoLite2-City.mmdb |

Environment Variables

| Variable | Purpose | Example | |----------|---------|---------| | TEMPS_DATABASE_URL | PostgreSQL connection | postgresql://user:pass@localhost:5432/temps | | TEMPS_ADDRESS | HTTP API address | 0.0.0.0:3000 | | TEMPS_TLS_ADDRESS | HTTPS proxy address | 0.0.0.0:443 | | TEMPS_CONSOLE_ADDRESS | Admin console address | 0.0.0.0:8081 | | TEMPS_DATA_DIR | Data directory | ~/.temps | | TEMPS_TOKEN | CLI API token | tk_abc123def456 | | TEMPS_API_URL | CLI API endpoint | https://temps.example.com |

Ports

| Port | Service | Purpose | |------|---------|---------| | 3000 | API (default) | HTTP API endpoint | | 80 | HTTP | HTTP traffic (recommended) | | 443 | HTTPS | TLS-encrypted traffic | | 8081 | Console | Admin web console | | 5432 | PostgreSQL | Database (if using Docker) | | 6379 | Redis | Cache (if using Docker) |

---

Next Steps

After installing Temps:

1. Deploy your first app: See deploy-to-temps skill
2. Add analytics: See add-react-analytics skill
3. Set up custom domain: See add-custom-domain skill
4. Configure MCP: See temps-mcp-setup skill

Documentation:

• CLI Reference: apps/temps-cli/SKILL.md
• Project Documentation: https://temps.sh/docs
• GitHub: https://github.com/gotempsh/temps

---

License: Dual-licensed under MIT or Apache 2.0