Deployment

General Deployment Steps

Before deploying to any specific platform, ensure you have:

1. Environment Setup: Install necessary dependencies (Bun, DuckDB)
2. Configuration: Run initial configuration (bun run prepare-config)
3. Database: Ensure database migrations are applied (bun migrate up)
4. Security: Set up authentication and secure your installation

Platform-Specific Deployment

Hetzner Deployment

Hetzner is a German cloud hosting provider that offers reliable, cost-effective servers. Here's how to deploy the Psyduck Analytics platform on Hetzner.

Prerequisites

• A Hetzner account with a server instance running
• SSH access to your server
• Basic knowledge of Linux server administration

Server Setup on Hetzner

1. Create a Hetzner Cloud Server

   • Go to the Hetzner Cloud Console
   • Create a new server with at least 2GB RAM (4GB recommended)
   • Choose Ubuntu 22.04 LTS as the operating system
   • Select an SSH key for access

2. Connect to Your Server

   ssh root@your-server-ip

3. Install Dependencies

   # Update system packages
   apt update && apt upgrade -y
   
   # Install Bun runtime
   curl -fsSL https://bun.sh/install | bash
   source /root/.bashrc
   
   # Install DuckDB
   apt install -y build-essential

4. Deploy Psyduck

   # Clone the repository
   git clone https://github.com/your-repo/psyduck.git
   cd psyduck
   
   # Install dependencies
   bun install
   
   # Build the application if needed
   # bun run build  # if there's a build step

5. Configure the Application

   # The application will automatically create a config file on first run
   # Run the configuration setup
   bun run prepare-config

6. Run as a Service To ensure the application runs reliably, set it up as a system service:

   Create a service file:

   nano /etc/systemd/system/psyduck.service

   Add the following configuration:

   [Unit]
   Description=Psyduck Analytics Service
   After=network.target
   
   [Service]
   Type=simple
   User=psyduck
   WorkingDirectory=/home/psyduck/psyduck
   ExecStart=/root/.bun/bin/bun run src/index.ts
   Restart=always
   RestartSec=10
   
   [Install]
   WantedBy=multi-user.target

   Then enable and start the service:

   # Create a dedicated user for security
   useradd -m -s /bin/bash psyduck
   cp -r /root/psyduck /home/psyduck/psyduck
   chown -R psyduck:psyduck /home/psyduck/psyduck
   
   # Reload systemd and enable the service
   systemctl daemon-reload
   systemctl enable psyduck
   systemctl start psyduck
   
   # Check the status
   systemctl status psyduck

7. Set Up a Reverse Proxy (Optional) For HTTPS and domain access, set up Nginx as a reverse proxy:

   # Install Nginx
   apt install nginx
   
   # Configure Nginx
   nano /etc/nginx/sites-available/psyduck

   Add the following configuration:

   server {
       listen 80;
       server_name your-domain.com;
       
       location / {
           proxy_pass http://localhost:9876;
           proxy_http_version 1.1;
           proxy_set_header Upgrade $http_upgrade;
           proxy_set_header Connection 'upgrade';
           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;
           proxy_cache_bypass $http_upgrade;
       }
   }

   Enable the site:

   ln -s /etc/nginx/sites-available/psyduck /etc/nginx/sites-enabled/
   nginx -t
   systemctl restart nginx

8. Enable HTTPS with Let's Encrypt

   # Install Certbot
   apt install certbot python3-certbot-nginx
   
   # Obtain certificate
   certbot --nginx -d your-domain.com
   
   # Certbot will automatically update your Nginx configuration

Security Considerations

• Use a firewall (ufw) to restrict access
• Regularly update the system and dependencies
• Use SSH keys instead of passwords
• Set up monitoring and backup solutions
• Keep your domain DNS settings secure

Scaling on Hetzner

For higher traffic loads, consider:

• Upgrading to a more powerful server instance
• Using Hetzner Load Balancers for multiple instances
• Setting up database backups and monitoring
• Using Hetzner's Object Storage for large datasets

Troubleshooting

Common issues and solutions:

• Port not accessible: Check firewall settings and security groups in Hetzner console
• Database errors: Ensure the data/ directory has proper write permissions
• Service won't start: Check logs with journalctl -u psyduck -f
• High memory usage: Monitor with htop and consider upgrading server specs if needed