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

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

{
  mjallen.services.tabby-web = {
    enable = true;
    port = 9000;
    openFirewall = true;
  };
}

Advanced Configuration

{
  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:

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

# 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:

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:

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;
    }
}