PuTTrY Start Script Guide

Quick reference for using the start.sh production start script.

Usage

./start.sh [OPTIONS]

Options

Option	Description
--help	Show help message
--build	Rebuild server before starting (npm run build:server)
--detach	Run server in background (daemon mode)

Examples

Development: Start in foreground

./start.sh

Runs the server in the foreground with full console output. Press Ctrl+C to stop.

Production: Build and start as daemon

./start.sh --build --detach

1. Rebuilds the server (with latest code)
2. Starts server in background
3. Prints the PID
4. Logs output to server.log

Quick restart

./start.sh --detach

Assumes server is already built. Fast startup.

Output

Foreground Mode

[INFO] Starting PuTTrY server...
[INFO] NODE_ENV=production
[INFO] Loading .env.local
[INFO] Loading ~/.puttry/.env
[startup] Loading env files from: [...]
[startup] ────────────────────────────────────────
[startup] Session Password
[startup] ────────────────────────────────────────
[startup] Password: grief-fools-glean-karma-8
[startup] URL: http://localhost:5174

Detach Mode

[INFO] Starting PuTTrY server...
[INFO] NODE_ENV=production
[INFO] Starting server in background...
[INFO] Server started with PID 3194
[INFO] Logs written to: /path/to/PuTTrY/server.log
3194

Environment Variables

The script automatically loads environment files in this order:

1. .env.local (if present, for local overrides)
2. ~/.puttry/.env (production configuration)
3. Process environment

Common variables:

PORT=5174                    # Server port
HOST=0.0.0.0                 # Bind address
AUTH_DISABLED=0              # Disable auth (0=enabled, 1=disabled)
NODE_ENV=production          # Always set to production
SESSION_PASSWORD_TYPE=xkcd   # Password format
TOTP_ENABLED=0               # Enable 2FA
SCROLLBACK_LINES=10000       # Terminal buffer size

Logging

Foreground

Output goes directly to console. Use Ctrl+C to stop.

Detached (background)

Output is written to server.log in the PuTTrY directory:

# Follow logs in real-time
tail -f server.log

# View last 50 lines
tail -n 50 server.log

# Search logs
grep "error" server.log

Starting/Stopping

Using start.sh

# Start
./start.sh --detach

# Stop (using puttry CLI)
puttry stop

# Or kill by PID
kill <PID>

Using puttry CLI (after npm link)

puttry start        # Start in background
puttry stop         # Stop server
puttry restart      # Restart
puttry status       # Check status

Using systemd (production servers)

See PRODUCTION.md for systemd setup.

sudo systemctl start puttry
sudo systemctl stop puttry
sudo systemctl status puttry
journalctl -u puttry -f

Troubleshooting

Port already in use

# Find process using port 5174
lsof -i :5174

# Or change the port
echo "PORT=5175" >> ~/.puttry/.env
./start.sh --detach

Server won’t start

# Try running in foreground to see errors
./start.sh

# Check if dist-server/server.js exists
ls -la dist-server/server.js

# If not, rebuild
./start.sh --build

# Check logs if running detached
cat server.log

Need to rebuild

./start.sh --build --detach

Integration with Process Managers

PM2

pm2 start "npm run build:server && node dist-server/server.js" --name puttry
pm2 save
pm2 startup

systemd (recommended for production)

See PRODUCTION.md for complete systemd setup.

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

Docker

docker run -d \
  -p 5174:5174 \
  -e PORT=5174 \
  -v ~/.puttry:/root/.puttry \
  puttry ./start.sh