--- name: static-files description: > Host static files on subdomains with optional authentication. Use when you need to serve HTML, images, CSS, JS, or any static content on a dedicated subdomain. Supports file upload, basic auth, quota management, and automatic SSL via Caddy. Commands include sf sites (create\/list\/delete), sf upload (files\/directories), sf files (list\/delete). --- # Static Files Hosting Host static content on `*.{domain}` subdomains with automatic SSL. > **Note:** The domain is configured via `SF_DOMAIN` environment variable (set during installation). > Examples below use `yourdomain.com` as placeholder. ## Quick Reference ```bash # Create site sf sites create mysite # → https:\/\/mysite.yourdomain.com (or your configured domain) # Upload file sf upload .\/index.html mysite # Upload directory sf upload .\/dist mysite # Add authentication sf sites auth mysite admin:secretpass123 # List files sf files mysite # Delete file sf files mysite delete path\/to\/file.txt # Delete site sf sites delete mysite ``` ## Environment Setup ```bash export SF_API_URL=http:\/\/localhost:3000 # API endpoint export SF_API_KEY=sk_xxxxx # Your API key export SF_DOMAIN=yourdomain.com # Your configured domain (optional, for URL display) ``` ## Workflows ### Deploy a Static Website ```bash # 1. Create the site sf sites create docs # 2. Upload the build directory sf upload .\/build docs # 3. Verify (replace with your domain) curl -I https:\/\/docs.yourdomain.com ``` ### Protected File Sharing ```bash # 1. Create site with auth sf sites create private sf sites auth private user:strongpassword # 2. Upload sensitive files sf upload .\/reports private # 3. Share URL + credentials # https:\/\/private.yourdomain.com (user \/ strongpassword) ``` ### Update Existing Files ```bash # Overwrite existing file sf upload .\/new-version.pdf mysite --overwrite # Or delete and re-upload sf files mysite delete old-file.pdf sf upload .\/new-file.pdf mysite ``` ## CLI Commands ### sites | Command | Description | |---------|-------------| | `sf sites list` | List all sites | | `sf sites create ` | Create new site | | `sf sites delete ` | Delete site and all files | | `sf sites auth ` | Set basic auth | | `sf sites auth --remove` | Remove auth | ### upload ```bash sf upload [subdir] [--overwrite] [--json] ``` - `path`: File or directory to upload - `site`: Target site name - `subdir`: Optional subdirectory - `--overwrite`: Replace existing files - `--json`: Output JSON ### files | Command | Description | |---------|-------------| | `sf files ` | List all files | | `sf files delete ` | Delete specific file | ### stats ```bash sf stats # Global stats sf stats # Site-specific stats ``` ## API Endpoints Base: `$SF_API_URL` with `Authorization: Bearer $SF_API_KEY` | Method | Path | Description | |--------|------|-------------| | GET | `\/sites` | List sites | | POST | `\/sites` | Create site | | DELETE | `\/sites\/{name}` | Delete site | | PATCH | `\/sites\/{name}` | Update auth | | GET | `\/sites\/{name}\/files` | List files | | POST | `\/sites\/{name}\/files` | Upload file | | DELETE | `\/sites\/{name}\/files\/{path}` | Delete file | | GET | `\/stats` | Global stats | | GET | `\/stats\/{name}` | Site stats | | GET | `\/health` | Health check | ## Constraints - **Site names**: lowercase, alphanumeric, hyphens only (max 63 chars) - **File size**: 50MB default (configurable) - **Quota**: 100MB per site default - **Rate limit**: 100 requests\/minute per API key ## Troubleshooting ### "Cannot connect to API" ```bash # Check service status systemctl status kleo-static-files # Check if port is listening curl http:\/\/localhost:3000\/health ``` ### "Invalid API key" ```bash # Verify key is set echo $SF_API_KEY # Create new key if needed bun run \/opt\/kleo-static-files\/scripts\/create-key.ts "new-key" ``` ### "Quota exceeded" ```bash # Check current usage sf stats mysite # Delete unused files sf files mysite delete large-file.zip ``` ### Site not accessible via HTTPS ```bash # Verify DNS points to server (use your domain) dig mysite.yourdomain.com # Check Caddy config cat \/etc\/caddy\/sites.d\/static-files.caddy # Resync Caddy bun run \/opt\/kleo-static-files\/scripts\/sync-caddy.ts --reload ``` ## Installation ### Server Installation (run once on host) ```bash curl -fsSL https:\/\/raw.githubusercontent.com\/498AS\/kleo-static-files\/main\/install.sh | sudo bash ``` The installer outputs JSON with connection details between `KLEO_SF_CONFIG_BEGIN` and `KLEO_SF_CONFIG_END` markers. Parse this to get `api_url` and `api_key`. ### After Installation ```bash export SF_API_URL=http:\/\/localhost:3000 export SF_API_KEY=sk_xxxxx # from installer output ``` ### Check Status ```bash sudo \/opt\/kleo-static-files\/install.sh --status ``` See [references\/install.md](references\/install.md) for manual installation. ## Alternative CLI (Shell Wrapper) If you need a lightweight alternative to the Bun CLI, use the curl-based shell wrapper: ```bash # Use directly \/opt\/kleo-static-files\/cli\/sf.sh sites list # Or create an alias alias sf='\/opt\/kleo-static-files\/cli\/sf.sh' # Works the same way sf sites create mysite sf upload .\/files mysite ``` The shell wrapper requires only `bash` and `curl`, no Bun installation needed.