---
name: temps-platform-setup
description: |
  Install, configure, and manage the Temps deployment platform and CLI. Covers self-hosted Temps installation, CLI setup (bunx @temps-sdk/cli), initial configuration, user management, and platform administration. Use when the user wants to: (1) Install Temps on their server, (2) Set up the Temps CLI, (3) Configure Temps for the first time, (4) Manage Temps platform settings, (5) Create admin users, (6) Configure DNS providers, (7) Set up TLS certificates. Triggers: "install temps", "setup temps", "temps cli", "configure temps", "temps platform", "self-hosted deployment platform".
---

# Temps Platform Setup & Management

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

## Table of Contents

- [Overview](#overview)
- [Installation Methods](#installation-methods)
- [Quick Start](#quick-start)
- [CLI Setup](#cli-setup)
- [Initial Configuration](#initial-configuration)
- [Platform Management](#platform-management)
- [DNS & TLS Setup](#dns--tls-setup)
- [Troubleshooting](#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)

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

# 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:**
```bash
temps --version
```

### Method 2: Docker Compose (Production)

For production deployments with PostgreSQL and Redis:

```bash
# 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)

```bash
# 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):**

```bash
# Create persistent volume
docker volume create temps-postgres

# Start PostgreSQL + TimescaleDB
docker run -d \
  --name temps-postgres \
  -v temps-postgres:/var/lib/postgresql/data \
  -e POSTGRES_USER=postgres \
  -e POSTGRES_PASSWORD=temps \
  -e POSTGRES_DB=temps \
  -p 16432:5432 \
  timescale/timescaledb:latest-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:

```bash
temps setup \
  --database-url "postgresql://postgres:temps@localhost:16432/temps" \
  --admin-email "your-email@example.com" \
  --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

```bash
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:

```bash
# 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)**

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

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

**Option 2: Install globally**

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

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

# Verify installation
temps --version
```

### Authentication

**Interactive login:**

```bash
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):**

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

**Using environment variables:**

```bash
# 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:**

```bash
temps whoami
```

**Example output:**
```
  Logged in as: admin@example.com
  Role: Admin
  API URL: https://temps.yourdomain.com
```

### Configuration

The CLI stores configuration in `~/.temps/`:

```bash
# 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

```bash
# 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:**

```bash
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:**

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

**List providers:**

```bash
temps git-providers list
```

### Create Environment

Environments isolate deployments (production, staging, development):

```bash
# 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:**

```bash
temps environments list
```

### Set Environment Variables

```bash
# 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:**

```bash
# Create user via CLI
temps users create \
  --email "developer@example.com" \
  --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:**

```bash
temps users list
```

### API Keys & Tokens

**Create API token:**

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

**Create API key:**

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

**List tokens:**

```bash
temps tokens list
```

### Service Provisioning

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

**PostgreSQL:**

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

**Redis:**

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

**S3 (MinIO):**

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

**List services:**

```bash
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:**

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

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

**View container logs:**

```bash
temps containers logs container-abc123 --follow
```

**Monitor deployments:**

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

# Show deployment status
temps deployments show 123
```

### Backups

**Create backup schedule:**

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

**Manual backup:**

```bash
temps backups run --service postgres-123
```

**List backups:**

```bash
temps backups list --service postgres-123
```

**Restore backup:**

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

---

## DNS & TLS Setup

### DNS Providers

Temps supports automatic DNS record management:

**Cloudflare:**

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

**AWS Route53:**

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

**DigitalOcean:**

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

**List providers:**

```bash
temps dns-providers list
```

### Custom Domains

**Add custom domain to project:**

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

**Add wildcard domain:**

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

**Verify DNS challenge (for TLS certificate):**

```bash
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:**

```bash
temps domains list --project my-app
```

### TLS Certificates

**Certificate orders:**

```bash
# 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):**

```bash
# 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](../temps-cli/SKILL.md) 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:**
```bash
# 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:**
```bash
# 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:**
```bash
# Verify DNS records exist
dig example.com
dig _acme-challenge.example.com TXT
```

2. **Verify DNS provider credentials:**
```bash
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:**
```bash
# 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:**
```bash
temps logs --deployment-id 123
```

2. **Verify build command:**
```bash
# Test locally
npm run build  # or your build command
```

3. **Check environment variables:**
```bash
temps env list --project my-app --environment production
```

4. **Test Docker build locally:**
```bash
docker build -t test-image .
docker run -p 3000:3000 test-image
```

### Service Connection Issues

**Error:** `Service postgres-123 not reachable`

**Solution:**
```bash
# 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:**
```bash
# 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:**
```bash
# 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:**
```bash
ls -lh ~/.temps/GeoLite2-City.mmdb
```

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

---

## Quick Reference

### Common Commands

```bash
# Platform
temps setup --database-url "postgres://..." --admin-email "admin@example.com"
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](../deploy-to-temps/SKILL.md)
2. **Add analytics**: See [add-react-analytics skill](../add-react-analytics/SKILL.md)
3. **Set up custom domain**: See [add-custom-domain skill](../add-custom-domain/SKILL.md)
4. **Configure MCP**: See [temps-mcp-setup skill](../temps-mcp-setup/SKILL.md)

**Documentation:**
- CLI Reference: [apps/temps-cli/SKILL.md](../../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