tabby-web testing

modules/nixos/services/tabby-web/README.md

@@ -0,0 +1,196 @@
+# Tabby Web Service Module
+
+This module provides a NixOS service for running the Tabby Web terminal application server.
+
+## Features
+
+- Systemd service with automatic startup
+- User and group management
+- Database migration on startup
+- Configurable environment variables
+- Security hardening
+- Firewall integration
+- Support for PostgreSQL and SQLite databases
+- Social authentication configuration
+
+## Basic Usage
+
+```nix
+{
+  mjallen.services.tabby-web = {
+    enable = true;
+    port = 9000;
+    openFirewall = true;
+  };
+}
+```
+
+## Advanced Configuration
+
+```nix
+{
+  mjallen.services.tabby-web = {
+    enable = true;
+    port = 8080;
+    openFirewall = true;
+    
+    # Use PostgreSQL instead of SQLite
+    databaseUrl = "postgresql://tabby:password@localhost:5432/tabby";
+    
+    # Use S3 for app distribution storage
+    appDistStorage = "s3://my-bucket/tabby-dist";
+    
+    # Configure social authentication
+    socialAuth = {
+      github = {
+        key = "your-github-oauth-key";
+        secret = "your-github-oauth-secret";
+      };
+      gitlab = {
+        key = "your-gitlab-oauth-key";
+        secret = "your-gitlab-oauth-secret";
+      };
+    };
+    
+    # Performance tuning
+    workers = 8;
+    timeout = 300;
+    
+    # Additional environment variables
+    extraEnvironment = {
+      DEBUG = "0";
+      LOG_LEVEL = "info";
+    };
+  };
+}
+```
+
+## Configuration Options
+
+### Basic Options
+
+- `enable`: Enable the tabby-web service
+- `port`: Port to run the server on (default: 9000)
+- `openFirewall`: Whether to open the firewall port (default: false)
+- `user`: User to run the service as (default: "tabby-web")
+- `group`: Group to run the service as (default: "tabby-web")
+- `dataDir`: Data directory (default: "/var/lib/tabby-web")
+
+### Database Configuration
+
+- `databaseUrl`: Database connection URL
+  - SQLite: `"sqlite:///var/lib/tabby-web/tabby.db"` (default)
+  - PostgreSQL: `"postgresql://user:password@host:port/database"`
+
+### Storage Configuration
+
+- `appDistStorage`: Storage URL for app distributions
+  - Local: `"file:///var/lib/tabby-web/dist"` (default)
+  - S3: `"s3://bucket-name/path"`
+  - GCS: `"gcs://bucket-name/path"`
+
+### Social Authentication
+
+Configure OAuth providers:
+
+```nix
+socialAuth = {
+  github = {
+    key = "oauth-key";
+    secret = "oauth-secret";
+  };
+  gitlab = {
+    key = "oauth-key";
+    secret = "oauth-secret";
+  };
+  microsoftGraph = {
+    key = "oauth-key";
+    secret = "oauth-secret";
+  };
+  googleOauth2 = {
+    key = "oauth-key";
+    secret = "oauth-secret";
+  };
+};
+```
+
+### Performance Options
+
+- `workers`: Number of gunicorn worker processes (default: 4)
+- `timeout`: Worker timeout in seconds (default: 120)
+
+### Additional Configuration
+
+- `extraEnvironment`: Additional environment variables as an attribute set
+
+## Service Management
+
+```bash
+# Start the service
+sudo systemctl start tabby-web
+
+# Enable automatic startup
+sudo systemctl enable tabby-web
+
+# Check service status
+sudo systemctl status tabby-web
+
+# View logs
+sudo journalctl -u tabby-web -f
+
+# Run management commands
+sudo -u tabby-web tabby-web-manage migrate
+sudo -u tabby-web tabby-web-manage add_version 1.0.156-nightly.2
+```
+
+## Security
+
+The service runs with extensive security hardening:
+
+- Dedicated user and group
+- Restricted filesystem access
+- No new privileges
+- Protected system directories
+- Private temporary directory
+- Memory execution protection
+- Namespace restrictions
+
+## Database Setup
+
+### PostgreSQL
+
+If using PostgreSQL, ensure the database and user exist:
+
+```sql
+CREATE USER tabby WITH PASSWORD 'your-password';
+CREATE DATABASE tabby OWNER tabby;
+```
+
+### SQLite
+
+SQLite databases are created automatically in the data directory.
+
+## Troubleshooting
+
+1. **Service fails to start**: Check logs with `journalctl -u tabby-web`
+2. **Database connection issues**: Verify database URL and credentials
+3. **Permission errors**: Ensure data directory has correct ownership
+4. **Port conflicts**: Check if another service is using the configured port
+
+## Integration with Reverse Proxy
+
+Example Nginx configuration:
+
+```nginx
+server {
+    listen 80;
+    server_name tabby.example.com;
+    
+    location / {
+        proxy_pass http://localhost:9000;
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $scheme;
+    }
+}