llms.txt
# Server Compass — AI Context File
> Server Compass is a desktop application (macOS, Windows, Linux) for managing VPS servers and deploying applications without terminal or DevOps expertise. It connects to any server via SSH and provides a visual interface for Docker deployments, domain management, monitoring, security, databases, file management, and more.
## Product Overview
Server Compass is a self-hosted alternative to Vercel, Heroku, Railway, and Render. Instead of paying per-resource cloud pricing, users pay a one-time $29 license and only their VPS hosting costs ($5–20/month). All data stays local on the user's machine — credentials, server configs, and SSH connections never pass through external servers.
**Supported platforms:** macOS 11+ (Intel & Apple Silicon), Windows 10/11 (64-bit), Linux (Ubuntu 20.04+, Debian 11+)
**Server requirements:** Any VPS with SSH access running Ubuntu 20.04+ or Debian 11+. Minimum 1 GB RAM (2 GB+ recommended). Docker is auto-installed by Server Compass if not present.
**Works with any VPS provider:** DigitalOcean, Hetzner, Vultr, Linode, AWS EC2, Google Cloud, Azure, OVH, Contabo, and any provider that gives SSH access.
---
## Core Concepts
### Servers
A "server" in Server Compass is any Linux VPS you connect to via SSH. You add servers by providing the IP address (or hostname), SSH port, username, and authentication method (SSH key or password). Server Compass stores credentials locally in an encrypted vault.
### Apps (Docker Stacks)
Every application deployed through Server Compass runs as a Docker Compose stack. A "stack" is one or more Docker containers defined by a `docker-compose.yml` file. Each stack gets its own project directory on the server under a managed path.
### Templates
Pre-built Docker Compose configurations for popular software. Server Compass includes 247+ one-click templates. Users can deploy templates without writing any Docker configuration.
### Domains
Server Compass uses Traefik as a managed reverse proxy to route custom domains to running apps. It handles SSL certificate generation and renewal automatically via Let's Encrypt.
---
## Features
### 1. Server Connection & Management
**Adding a server:**
1. Click "Add Server" in the sidebar or dashboard.
2. Choose authentication method — SSH Key (recommended) or Password.
3. If using SSH key: select an existing key from `~/.ssh` or generate a new key pair.
4. Enter server name, hostname/IP address, SSH port (default 22), and username (usually `root`).
5. Click "Test Connection" to verify.
6. Save. The server appears in the sidebar.
**Server features:**
- **Favorite servers** — Star servers to pin them at the top of the list.
- **Lock server** — Mark production servers as read-only to prevent accidental destructive changes. When locked, deploy, delete, and configuration changes are blocked.
- **Multi-window** — Open individual server dashboards in separate windows for side-by-side management.
- **Drag-and-drop reordering** — Organize your server list manually.
- **Privacy mode** — Hide sensitive data like IP addresses and server names from the UI (useful for screen sharing or screenshots).
**Server dashboard tabs:**
Each server has these tabs: Overview, Apps, Domain, Cron, Folders, Git, Terminal, Monitor, Security, Advance, Settings.
---
### 2. Application Deployment
Server Compass offers multiple ways to deploy applications:
#### A. Deploy from App Templates (247+ templates)
1. Go to server → Apps tab → "Deploy new app."
2. Select "App Template."
3. Browse or search templates by category.
4. Select a template. The Compose editor opens with pre-configured `docker-compose.yml`.
5. Review and optionally modify the configuration.
6. Environment variables are shown with auto-generated secrets (passwords, keys).
7. Click "Deploy." Real-time logs show progress.
8. When complete, the app appears in the Apps list.
**Template categories:**
- **Databases:** PostgreSQL, MySQL, MariaDB, MongoDB, Redis, Elasticsearch, ClickHouse, InfluxDB, SurrealDB, Weaviate, Cassandra, CouchDB, Kafka, SQL Server, TimescaleDB, Meilisearch, Typesense, and more.
- **Applications:** WordPress, Ghost, Strapi, Directus, Drupal, Joomla, Plausible Analytics, Umami, Metabase, Mattermost, Rocket.Chat, Chatwoot, OpenProject, Plane, Nextcloud, BookStack, Docmost, Affine, Joplin, and 80+ more.
- **AI & Machine Learning:** AnythingLLM, Flowise, Langflow, Ollama, Open WebUI, Label Studio, Qdrant, Chroma, and more.
- **Media:** Plex, Emby, Audiobookshelf, Navidrome, Sonarr, Radarr, Prowlarr, Lidarr, Bazarr, Overseerr, and more.
- **Development tools:** Code Server (VS Code in browser), Jupyter, Gitea, Forgejo, Harbor, PgAdmin, CloudBeaver, and more.
- **Infrastructure:** Prometheus, Grafana, Uptime Kuma, Pi-hole, RabbitMQ, Mosquitto, Cloudflared, Portainer, FileBrowser, and more.
- **Email:** Mailserver, Listmonk, Mautic.
#### B. Deploy from GitHub
1. Go to Dashboard → Git tab → connect your GitHub account (device flow OAuth — no tokens to paste).
2. Link the GitHub account to your server.
3. Go to server → Apps tab → "Deploy new app" → select "Your Code: GitHub."
4. Choose the GitHub account, repository, and branch.
5. Server Compass auto-detects:
- Existing `docker-compose.yml` in the repo.
- Framework (Next.js, Nuxt, Django, Rails, etc.) and generates a Dockerfile if none exists using Nixpacks.
6. Review/edit compose file and environment variables.
7. Click "Deploy."
8. The app tracks git metadata (repo, branch, last commit) for future redeployments.
**Supported frameworks for auto-detection:** Next.js, Nuxt.js, SvelteKit, Remix, Django, FastAPI, Flask, Ruby on Rails, Spring Boot, Go (Gin, Echo), PHP (Laravel), and static sites.
#### C. Deploy from Docker Registry
1. Go to server → Apps tab → "Deploy new app" → select "Pull from Registry."
2. Enter the image name (e.g., `nginx:latest`, `ghcr.io/org/app:v2`).
3. For private registries, enter authentication credentials.
4. Server Compass auto-detects common image ports.
5. Configure environment variables and port mappings.
6. Deploy.
**Supported registries:** Docker Hub, GitHub Container Registry (GHCR), Amazon ECR, Google GCR, and any private Docker registry.
#### D. Upload Code to Deploy
1. Drag and drop a folder into the deploy wizard.
2. Server Compass auto-detects the framework and generates a Dockerfile.
3. Review and deploy.
#### Deployment Features
- **Environment Variables Editor** — Visual `.env` editor with encrypted vault storage. Auto-generates secure passwords and secrets for database templates.
- **Port conflict detection** — Warns if a port is already in use on the server before deploying.
- **Compose editor** — Full YAML editor with syntax highlighting for reviewing and modifying `docker-compose.yml`.
- **Deployment history** — Every deploy attempt is logged with timestamp, status, and full logs.
---
### 3. App Management
After deployment, manage apps from the Apps tab:
- **Grid or Table view** — Toggle between visual cards and a compact table.
- **Container controls** — Start, stop, restart, or delete individual apps.
- **Redeploy** — Pull latest images, rebuild, and restart with one click.
- **Real-time logs** — Stream container logs with search and filtering.
- **Environment variables** — Edit `.env` and redeploy.
- **Disk usage** — See how much space each app uses (images, volumes, containers, app folder).
**App detail dashboard:** Click any app to see its full dashboard with overview, environment variables, port mappings, deployment strategy, container details, and deployment history.
#### Zero-Downtime Deployment
For apps with domains configured, Server Compass supports zero-downtime (blue-green) deployment:
1. A new "staging" container is started alongside the existing one.
2. Health checks run against the staging container.
3. If healthy, Traefik switches traffic to the new container.
4. The old container is removed.
5. If the staging container fails health checks, it is removed and the old container continues serving traffic.
#### Rollback
If a deployment fails or causes issues, you can roll back to any previous deployment from the deployment history.
---
### 4. Domain Management & SSL
**Setting up a domain:**
1. Go to server → Domain tab.
2. If this is the first domain on this server, Server Compass installs Traefik (the managed reverse proxy) automatically.
3. Click "Add Domain."
4. Enter the domain name (e.g., `app.example.com` or `example.com`).
5. Select the target app/container or enter a custom port number.
6. Follow the DNS instructions shown (point an A record to your server's IP).
7. Click "Verify Domain" — Server Compass checks DNS propagation.
8. Once verified, an SSL certificate is automatically issued via Let's Encrypt.
9. The domain is now live with HTTPS.
**Domain features:**
- **Automatic SSL** — Free Let's Encrypt certificates with automatic renewal.
- **WWW redirect** — Toggle whether `www.example.com` redirects to `example.com` or vice versa.
- **URL redirects** — Configure 301/302 redirects.
- **Certificate viewer** — View SSL certificate details, expiry, and one-click renewal.
- **Security headers** — Configure CORS, HSTS, and other security headers.
- **Trust proxy headers** — Presets for Cloudflare, AWS ALB, DigitalOcean, and Hetzner load balancers to preserve real visitor IP addresses.
**Reverse proxy options:**
- **Traefik (managed)** — Server Compass handles everything. This is the default and recommended option.
- **External proxy** — Use your existing Nginx, Caddy, or CloudPanel alongside Server Compass. Configure your proxy to forward traffic to the ports Server Compass exposes.
- **CloudPanel integration** — If you have CloudPanel installed, Server Compass can manage CloudPanel sites and offers one-click migration to Traefik.
- **None** — No proxy management; handle domains yourself.
---
### 5. SSH Terminal
Server Compass includes a full interactive SSH terminal:
1. Go to server → Terminal tab.
2. A terminal session opens automatically.
3. Type commands as you would in any terminal.
**Terminal features:**
- **Multi-tab** — Open multiple terminal sessions to the same server.
- **Command suggestions** — Auto-complete for common commands.
- **Auto-correction** — Fixes common typos (e.g., `sl` → `ls`, `docer` → `docker`).
- **Clickable links** — URLs in terminal output are clickable.
- **Font size zoom** — Ctrl/Cmd + mouse wheel to adjust.
- **Download logs** — Save the terminal session as a `.txt` file.
- **Standalone window** — Pop the terminal out into its own window.
---
### 6. File Management
A visual file browser for your server:
1. Go to server → Folders tab.
2. Browse the directory tree.
3. Click files to view or edit them.
**File management features:**
- **List or tree view** — Switch between flat list and hierarchical tree.
- **File editor** — Edit files with syntax highlighting and save directly to the server.
- **Upload files/folders** — Drag and drop to upload.
- **Download files** — Download any file directly.
- **Create, rename, delete** — Full file operations from the UI.
---
### 7. Cron Jobs
Manage scheduled tasks visually:
1. Go to server → Cron tab.
2. Click "Add Cron Job."
3. Enter the command to run.
4. Set the schedule using either:
- **Visual picker** — Dropdowns for "every day at 3am", "every Monday", "every hour", etc.
- **Cron syntax** — Standard cron expressions (e.g., `0 3 * * *`).
5. Add a description and set the owner (user that runs the job).
6. Save. The cron job is installed on the server immediately.
**Cron features:**
- **Templates** — Pre-built jobs for common tasks (database backups, log cleanup, health checks).
- **Execution logs** — View output and success/failure status of past runs.
- **Enable/disable** — Pause a cron job without deleting it.
- **SSH preview** — See the exact command that will be executed on the server.
---
### 8. Database Administration
Server Compass includes a visual database management interface:
**Supported databases:** PostgreSQL, MySQL, MariaDB, MongoDB, Redis, Elasticsearch, ClickHouse, InfluxDB, SurrealDB, Weaviate, CouchDB, Cassandra, SQL Server (MSSQL), and variants (TimescaleDB, Hydra, Valkey, KeyDB, ScyllaDB).
**DbAdmin features:**
- **Browse tables/collections** — Visual data browser.
- **Run queries** — SQL query editor for relational databases; query editors for MongoDB, SurrealDB, Weaviate.
- **Import data** — Upload `.sql` files or CSV data.
- **Export data** — Download database dumps.
- **Connection credentials** — View and copy credentials for external access.
- **Database commands** — Pre-filled CLI commands for connecting via terminal.
- **Provision databases** — Create new database instances from templates with configured credentials.
**How to access DbAdmin:**
1. Deploy a database from the templates (e.g., PostgreSQL).
2. Go to the app detail page for the database.
3. The database management UI appears automatically based on the detected database type.
---
### 9. Monitoring & Alerts
**Real-time server metrics:**
- CPU usage (per-core and aggregate)
- Memory usage and capacity
- Disk usage by mount point
- Network throughput (inbound/outbound)
- Disk I/O (read/write)
Metrics are shown as charts with 180-point history on the server Overview tab.
**Setting up alerts:**
1. Go to server → Monitor tab.
2. Install the monitoring agent (one-click install).
3. Create alert rules with thresholds (e.g., "alert when CPU > 90% for 5 minutes").
4. Add notification channels:
- **Email** — Send alerts to email addresses.
- **Webhook** — POST to any URL.
- **Slack** — Send to a Slack channel.
5. Test the notification channel.
6. Alerts fire automatically when thresholds are crossed.
**Deployment notifications:**
Get notified when deployments succeed or fail, through the same notification channels.
---
### 10. Security
**Security audit:**
Go to server → Security tab to see an overall security score with breakdown:
- **Fail2Ban** — Brute-force protection status.
- **UFW Firewall** — Firewall rules and status.
- **SSH hardening** — Configuration audit (root login, password auth, etc.).
- **Auto-updates** — Whether automatic security updates are enabled.
**Fail2Ban management:**
- View jail status and currently banned IPs.
- Configure ban duration and max retries.
- Whitelist trusted IP ranges.
**Firewall (UFW) management:**
- View all firewall rules.
- Add or remove rules (port, protocol, action).
- Enable/disable individual rules.
**SSH hardening:**
- View current SSH configuration.
- Check whether root login is disabled.
- Check whether password authentication is disabled.
- Get recommendations to improve security.
**User management:**
- Create system users.
- Manage SSH access per user.
---
### 11. Backups & Disaster Recovery
#### Server Snapshots
Export an entire server configuration as an encrypted `.scz` file:
1. Go to server → Settings tab → Backups.
2. Click "Export Server."
3. Choose components to include: Docker stacks, volumes, databases, domains, cron jobs, alert rules, SSH keys.
4. Set an encryption password.
5. Export locally or upload to S3-compatible storage.
**Restore a snapshot:**
1. On the target server, go to Settings → Backups → Import.
2. Select the `.scz` file.
3. Enter the encryption password.
4. Choose domain handling (keep, strip, or remap domains).
5. Restore. All selected components are rebuilt on the new server.
**Use cases:**
- **Disaster recovery** — Restore to the same server after a failure.
- **Server migration** — Move everything to a new server or provider.
- **Server cloning** — Duplicate a server setup for staging or testing.
#### Cross-Device Sync
Sync your Server Compass configuration across multiple machines:
1. Go to Dashboard → Settings → Backups.
2. Configure S3 storage (AWS S3, Backblaze B2, Wasabi, or any S3-compatible).
3. Push your config to the cloud (encrypted end-to-end).
4. On another machine, pull the config.
5. All servers, credentials, and settings sync.
#### Selective Backup
- Choose which servers to include in exports.
- Manual export to encrypted file for offline backup.
- Cloud backup to S3 with per-server selection.
---
### 12. GitHub Integration
**Connecting GitHub:**
1. Go to Dashboard → Git tab.
2. Click "Connect GitHub Account."
3. A device code is shown — enter it on github.com/login/device.
4. Authorize Server Compass.
5. Your GitHub account is linked. Tokens are stored in your OS keychain (macOS Keychain, Windows Credential Manager, Linux keyring).
**Per-server Git setup:**
- Link one or more GitHub accounts to each server.
- Server Compass manages SSH keys for private repository access.
- Set a default account per server.
**Deploying from GitHub:**
See "Deploy from GitHub" in the Deployment section above.
---
### 13. Disk Management
Identify and clean up disk space:
1. Go to server → Overview tab → Disk section.
2. The disk scanner shows usage by category:
- Docker images
- Docker build cache
- Dangling volumes
- Stopped containers
- System logs and journal
- APT cache
- Temp files
- npm cache
- PM2 logs
3. Select categories to clean up.
4. Click "Clean" for one-click removal.
**Per-app disk usage:**
Each app shows its own disk breakdown (images, volumes, containers, app folder) in the app detail page.
---
### 14. Server Migration
Migrate from other platforms to Server Compass:
- **From RunCloud** — Auto-detect and import apps.
- **From Coolify** — Import existing deployments.
- **From Laravel Forge** — Import server configuration.
- **From CloudPanel** — One-click migration to Traefik-managed domains.
---
### 15. Built-in Developer Tools
Server Compass includes tools accessible from the app:
- **Dockerfile Generator** — Generate Dockerfiles for various frameworks.
- **Nginx Config Generator** — Create Nginx configurations.
- **GitHub Actions Generator** — Generate CI/CD workflow files.
- **SSL Checker** — Verify SSL certificate status and chain.
- **Security Headers Checker** — Audit HTTP security headers.
- **PM2 Config Generator** — Create PM2 ecosystem files.
- **Cron Expression Builder** — Build and validate cron expressions.
- **SSH Config Generator** — Generate SSH config entries.
- **JWT Secret Generator** — Generate secure JWT secrets.
- **Regex Tester** — Test regular expressions.
- **Docker Compose Validator** — Validate compose files.
---
## Licensing & Pricing
- **Free tier:** 1 server, 1 deployment, 1 domain, 5 cron jobs, 20 command logs. No database provisioning.
- **Pro license:** $29 one-time payment. Unlimited servers, deployments, domains, cron jobs, and command logs. Database provisioning included.
- **Device licenses:** Single device, 3-device, or 5-device options.
- **Updates:** 1 year of updates included. Optional renewal for continued updates.
- **No subscriptions, no per-seat pricing, no usage-based billing.**
**Total cost of self-hosting with Server Compass:**
$29 one-time + VPS cost ($5–20/month depending on provider and specs).
---
## Troubleshooting
### Connection Issues
**"Connection refused" or "Connection timed out"**
- Verify the server IP address is correct.
- Ensure the SSH port (default 22) is open in your server's firewall.
- Check that the server is running and accessible.
- If using a cloud provider, verify the security group or firewall allows inbound SSH.
**"Authentication failed"**
- If using SSH key: ensure the public key is in `~/.ssh/authorized_keys` on the server.
- If using password: verify the password is correct.
- Check that the username is correct (usually `root` for new servers).
- Some providers disable password auth by default — use SSH key instead.
**"Host key verification failed"**
- The server's host key has changed (common after server rebuild). Remove the old key from your `~/.ssh/known_hosts` file or let Server Compass handle it.
### Deployment Issues
**"Port already in use"**
- Another a
