Self-Hosting

Documentation Index

Fetch the complete documentation index at: https://docs.yespapa.io/llms.txt

Use this file to discover all available pages before exploring further.

• Option 1: Docker — A standalone Node.js server you run yourself. Recommended for self-hosting.
• Option 2: Supabase — The hosted cloud option (or self-hosted Supabase). This is the current default.

​

Option 1: Docker (Recommended for Self-Hosting)

​

Prerequisites

• Docker and Docker Compose

​

Quick Start

docker run -d \
  --name yespapa-server \
  -p 8080:8080 \
  -e JWT_SECRET=$(openssl rand -base64 32) \
  -v yespapa-data:/app/data \
  --restart unless-stopped \
  skyaiops/yespapa-server:latest

services:
  yespapa-server:
    image: skyaiops/yespapa-server:latest
    ports:
      - "8080:8080"
    environment:
      - PORT=8080
      - JWT_SECRET=change-me-to-a-random-string
      - DATABASE_PATH=/app/data/yespapa.db
      - EXPO_PUSH_ENABLED=false
    volumes:
      - yespapa-data:/app/data
    restart: unless-stopped

volumes:
  yespapa-data:

docker compose up -d

curl http://localhost:8080/health
# Expected: {"status":"ok","version":"0.1.0"}

​

Configuration

openssl rand -base64 32

environment:
  - JWT_SECRET=your-generated-secret-here

​

Data Persistence

docker compose cp yespapa-server:/app/data/yespapa.db ./yespapa-backup.db

​

Connecting YesPaPa to Your Docker Server

Remote server URL: http://your-server-ip:8080
Remote server type: selfhosted

yespapa uninstall && yespapa init

​

API Endpoints

​

Push Notifications

1. Set EXPO_PUSH_ENABLED=true in docker-compose.yml
2. Restart the container: docker compose restart

​

Running Without Docker

cd server
npm install
npm run build
JWT_SECRET=your-secret-here npm start

​

Updating

docker pull skyaiops/yespapa-server:latest
docker compose up -d

docker pull skyaiops/yespapa-server:0.2.0
# Update the image tag in docker-compose.yml, then:
docker compose up -d

​

Docker Troubleshooting

​

Container fails to start

• Check logs: docker compose logs yespapa-server
• Ensure port 8080 is not in use: lsof -i :8080
• Verify the Docker volume exists: docker volume ls | grep yespapa-data

​

”Connection refused” from YesPaPa daemon

• Ensure the server is running: docker compose ps
• If the daemon is on the same machine, use http://localhost:8080 or http://host.docker.internal:8080
• If on a different machine, ensure the server port is accessible (check firewalls)
• Verify with: curl http://your-server-ip:8080/health

​

Database errors or corruption

• Stop the server: docker compose down
• Back up the current database from the volume
• Remove the volume to start fresh: docker volume rm server_yespapa-data
• Restart: docker compose up -d

​

WebSocket connection drops

• If behind a reverse proxy (nginx, Caddy), ensure WebSocket upgrade is configured
• For nginx, add to your location block:
  proxy_http_version 1.1;
  proxy_set_header Upgrade $http_upgrade;
  proxy_set_header Connection "upgrade";
  

​

Option 2: Supabase (Hosted / Cloud)

​

What You Need

• A Supabase project (free tier works)
• The Supabase CLI (npx supabase)

​

Setup Steps

​

1. Create a Supabase Project

• Project URL: https://<your-project-ref>.supabase.co
• Anon Key: Found in Settings > API > Project API keys > anon public
• Service Role Key: Found in Settings > API > Project API keys > service_role (used by Edge Functions only, never exposed to clients)

​

2. Apply Database Migrations

# Link to your Supabase project
npx supabase link --project-ref <your-project-ref>

# Apply migrations
npx supabase db push

​

3. Enable Realtime

​

4. Deploy Edge Functions

npx supabase functions deploy push_notification

• SUPABASE_URL
• SUPABASE_SERVICE_ROLE_KEY

​

5. Enable Anonymous Auth

1. Go to Authentication > Providers in your Supabase dashboard
2. Enable Anonymous Sign-ins

​

6. Configure YesPaPa to Use Your Supabase Server

Remote server URL [https://remote.yespapa.io]: https://your-project.supabase.co
Remote server key [default]: your-anon-key-here

# The daemon reads these from ~/.yespapa/yespapa.db config table
# You can reinitialize with: yespapa uninstall && yespapa init

​

Schema Reference

​

hosts Table

create table public.hosts (
  id uuid primary key default gen_random_uuid(),
  user_id uuid references auth.users not null default auth.uid(),
  host_name text not null,
  host_fingerprint text unique not null,
  push_token text,
  last_seen_at timestamptz default now(),
  created_at timestamptz default now() not null
);

​

commands Table

create table public.commands (
  id text primary key,
  host_id uuid references public.hosts(id) on delete cascade not null,
  command_display text not null,
  justification text,
  status text not null default 'pending'
    check (status in ('pending', 'approved', 'denied')),
  totp_code text,
  denial_message text,
  timeout_seconds integer default 0,
  created_at timestamptz default now() not null,
  resolved_at timestamptz
);

​

grace_periods Table

create table public.grace_periods (
  id text primary key,
  host_id uuid references public.hosts(id) on delete cascade not null,
  scope text not null,
  expires_at timestamptz not null,
  hmac_signature text not null,
  created_at timestamptz default now() not null
);

​

RLS Policies

-- hosts: direct ownership
create policy "users_own_hosts" on public.hosts
  for all using (auth.uid() = user_id);

-- commands: owned via host
create policy "users_own_commands" on public.commands
  for all using (
    host_id in (select id from public.hosts where user_id = auth.uid())
  );

-- grace_periods: owned via host
create policy "users_own_grace" on public.grace_periods
  for all using (
    host_id in (select id from public.hosts where user_id = auth.uid())
  );

​

Supabase Troubleshooting

​

”Remote connection failed” during init

• Verify the URL is correct and includes https://
• Check that the anon key is the anon key, not the service_role key
• Ensure anonymous auth is enabled in your Supabase project

​

Push notifications not arriving

• Verify the Edge Function is deployed: npx supabase functions list
• Check Edge Function logs: npx supabase functions logs push_notification
• Ensure the mobile app has a valid push token (check hosts.push_token in the database)

​

Commands stuck as “pending”

• Check Realtime is enabled for the commands table
• Verify the daemon is connected: yespapa status should show “Remote: configured”
• Check daemon logs: cat ~/.yespapa/daemon.log

​

Security Considerations

​

Zero-Trust Architecture

• TOTP codes are validated locally by the daemon, not by the server
• Grace tokens are HMAC-signed with the TOTP seed, which never leaves the machine
• The server is a relay — it forwards approval requests and responses, but cannot forge approvals
• If the server is compromised, the worst case is denial of service (commands stuck pending). Attackers cannot approve commands

​

Recommended Hardening

1. Use TLS — Always use HTTPS in production. For the Docker server, place it behind a reverse proxy (nginx, Caddy, Traefik) with TLS termination
2. Set a strong JWT secret — For the Docker server, use a randomly generated string of at least 32 characters
3. Restrict network access — Limit who can reach the server port. Use firewall rules or bind to a private network
4. Set up monitoring — Watch for unusual patterns in the commands table
5. Back up your database — Especially host registrations and push tokens
6. Rotate secrets — Periodically rotate JWT secrets (Docker) or API keys (Supabase) and update client configs

​

Alternative Backends

• Self-hosted Supabase — Run the full Supabase stack on your own infrastructure using the migrations in supabase/
• PostgreSQL + PostgREST + pg_notify — Same REST+realtime pattern without Supabase
• Firebase — Firestore + Cloud Functions + FCM
• Custom server — Any language/framework that provides REST + WebSocket + push notifications

1. A REST API for CRUD on hosts, commands, grace_periods
2. Real-time subscriptions for commands and grace_periods changes
3. A push notification endpoint (Expo Push API compatible)
4. Token-based authentication (JWT or equivalent)