PuTTrY Production Deployment Guide

This guide covers deploying PuTTrY in a production environment.

Quick Start

Using the start script

The simplest way to start the server:

# Build and start in foreground
./start.sh --build

# Start in background (daemon mode)
./start.sh --detach

# Just start (assumes already built)
./start.sh

Using the CLI

After npm link, you can use the global puttry command:

puttry start       # Start server in background
puttry status      # Check if server is running
puttry password    # Get current session password
puttry stop        # Stop the server

Production Setup (Systemd)

For automatic startup and restart on system boot, use systemd.

Installation Steps

1. Install dependencies (assuming Debian/Ubuntu):

   sudo apt-get update
   sudo apt-get install nodejs npm
   

2. Create puttry user:

   sudo useradd -r -s /bin/bash -d /home/puttry puttry
   sudo mkdir -p /home/puttry/.puttry
   sudo chown -R puttry:puttry /home/puttry/.puttry
   

3. Install PuTTrY:

   sudo mkdir -p /opt/puttry
   sudo chown puttry:puttry /opt/puttry
   cd /tmp && git clone <your-repo> puttry-tmp
   sudo mv puttry-tmp/* /opt/puttry/
   cd /opt/puttry
   sudo -u puttry npm ci --production
   sudo -u puttry npm run build:server
   

4. Setup environment file:

   sudo nano /opt/puttry/.env
   

   Add configuration:

   PORT=5174
   HOST=0.0.0.0
   AUTH_DISABLED=0
   SESSION_PASSWORD_TYPE=xkcd
   SESSION_PASSWORD_LENGTH=4
   TOTP_ENABLED=0
   LOG_SESSION_PASSWORD=1
   SCROLLBACK_LINES=10000
   RATE_LIMIT_GLOBAL_MAX=500
   RATE_LIMIT_SESSION_PASSWORD_MAX=10
   

5. Install systemd service:

   sudo cp /opt/puttry/puttry.service /etc/systemd/system/
   sudo systemctl daemon-reload
   sudo systemctl enable puttry
   sudo systemctl start puttry
   

6. Verify service:

   sudo systemctl status puttry
   journalctl -u puttry -f  # Follow logs
   

Configuration

Environment Variables

Configure via /opt/puttry/.env or /home/puttry/.puttry/.env:

Variable	Default	Description
PORT	5174	Server port
HOST	0.0.0.0	Bind address
AUTH_DISABLED	0	Disable authentication (0=enabled, 1=disabled)
SESSION_PASSWORD_TYPE	xkcd	Password format: xkcd or random
SESSION_PASSWORD_LENGTH	4	Number of words/chars
TOTP_ENABLED	0	Enable TOTP 2FA
LOG_SESSION_PASSWORD	1	Log password on startup
PASSKEY_RP_ORIGIN	(empty)	Passkey origin (auto-detect if empty)
RATE_LIMIT_GLOBAL_MAX	500	Global rate limit per minute
RATE_LIMIT_SESSION_PASSWORD_MAX	10	Login attempts per minute
SCROLLBACK_LINES	10000	Terminal scrollback buffer

Using CLI to Configure

After deployment, use the CLI to manage settings:

# List current configuration
puttry config list

# Update a setting
puttry config set SCROLLBACK_LINES 5000

# Rotate session password
puttry password rotate

# Check server status
puttry status

Managing the Service

Systemd Commands

# Start service
sudo systemctl start puttry

# Stop service
sudo systemctl stop puttry

# Restart service
sudo systemctl restart puttry

# View status
sudo systemctl status puttry

# View logs
journalctl -u puttry -f

# Disable auto-start on boot
sudo systemctl disable puttry

# Enable auto-start on boot
sudo systemctl enable puttry

Reverse Proxy Setup

Nginx

server {
    listen 80;
    server_name your-domain.com;

    # Redirect HTTP to HTTPS
    return 301 https://$server_name$request_uri;
}

server {
    listen 443 ssl http2;
    server_name your-domain.com;

    ssl_certificate /etc/ssl/certs/your-cert.crt;
    ssl_certificate_key /etc/ssl/private/your-key.key;

    location / {
        proxy_pass http://localhost:5174;
        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_connect_timeout 60s;
        proxy_send_timeout 60s;
        proxy_read_timeout 60s;
    }

    location /terminal {
        proxy_pass http://localhost:5174;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_read_timeout 86400s;
        proxy_send_timeout 86400s;
    }

    location /sync {
        proxy_pass http://localhost:5174;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_read_timeout 86400s;
    }
}

Apache

<VirtualHost *:80>
    ServerName your-domain.com
    Redirect permanent / https://your-domain.com/
</VirtualHost>

<VirtualHost *:443>
    ServerName your-domain.com

    SSLEngine on
    SSLCertificateFile /etc/ssl/certs/your-cert.crt
    SSLCertificateKeyFile /etc/ssl/private/your-key.key

    ProxyPreserveHost On
    ProxyRequests Off

    # WebSocket support
    RewriteEngine On
    RewriteCond %{HTTP:Upgrade} websocket [NC]
    RewriteCond %{HTTP:Connection} upgrade [NC]
    RewriteRule ^/(.*)$ "ws://localhost:5174/$1" [P,L]

    # Regular proxying
    ProxyPass / http://localhost:5174/
    ProxyPassReverse / http://localhost:5174/
</VirtualHost>

Monitoring

Check Service Health

# View service status
systemctl status puttry

# Follow real-time logs
journalctl -u puttry -f

# View recent errors
journalctl -u puttry -p err

Monitor Port Availability

# Check if port 5174 is listening
lsof -i :5174
ss -tlnp | grep 5174

Database/State Directory

PuTTrY stores state in ~/.puttry/:

# View configuration
cat /home/puttry/.puttry/.env

# View session password
cat /home/puttry/.puttry/session-password.txt

# View 2FA state
cat /home/puttry/.puttry/2fa-state.json

Troubleshooting

Service won’t start

# Check systemd errors
systemctl status puttry
journalctl -u puttry -n 50

# Check permissions
ls -la /home/puttry/.puttry
ls -la /opt/puttry/dist-server/

# Manually test the server
sudo -u puttry node /opt/puttry/dist-server/server.js

Port already in use

# Find what's using the port
lsof -i :5174

# Kill the process (if needed)
kill -9 <PID>

# Or change the port
echo "PORT=5175" >> ~/.puttry/.env
systemctl restart puttry

Authentication issues

# Reset session password
rm /home/puttry/.puttry/session-password.txt
systemctl restart puttry

# Check new password in logs
journalctl -u puttry | grep "Session Password"

Backup and Recovery

Backup configuration

sudo tar -czf puttry-backup-$(date +%Y%m%d).tar.gz \
    /home/puttry/.puttry/ \
    /opt/puttry/.env

Restore configuration

sudo tar -xzf puttry-backup-20240101.tar.gz -C /
sudo chown -R puttry:puttry /home/puttry/.puttry
systemctl restart puttry

Updates

Update to new version

cd /opt/puttry
sudo -u puttry git pull origin main
sudo -u puttry npm ci --production
sudo -u puttry npm run build:server
sudo systemctl restart puttry

# Verify
systemctl status puttry

Performance Tuning

Node.js options

Edit /etc/systemd/system/puttry.service:

[Service]
ExecStart=/usr/bin/node --max-old-space-size=2048 /opt/puttry/dist-server/server.js

Then reload:

sudo systemctl daemon-reload
sudo systemctl restart puttry

Increase file descriptor limits

Edit /etc/security/limits.conf:

puttry soft nofile 65536
puttry hard nofile 65536

Then:

sudo systemctl restart puttry

Security Considerations

1. Always use HTTPS in production
2. Keep session passwords strong - use longer passwords for sensitive deployments
3. Enable TOTP 2FA for additional security
4. Use environment variables for sensitive config, not hardcoded values
5. Regular backups of ~/.puttry/ directory
6. Monitor logs for suspicious activity
7. Update regularly when new versions are available
8. Firewall rules - only expose to trusted networks if needed