Add comprehensive documentation in docs/ directory
docs/deployment.md: - Complete deployment guide for both automated and manual setup - Step-by-step instructions for Debian 12 ARM64 - Custom Caddy build with rate limiting plugin - Service configuration and security setup - Troubleshooting and maintenance sections - Performance tuning recommendations docs/api.md: - Comprehensive API documentation with examples - All public and admin endpoints documented - Request/response schemas and validation rules - Authentication flows and error handling - Rate limiting and security feature documentation - Client library examples (JavaScript, curl) Fixes README.md reference to non-existent docs/deployment.md. Both files provide detailed technical documentation for: - Deployment procedures and requirements - API usage and integration - Security features and limitations - Troubleshooting and maintenance 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
Claude Code
parent
1918217449
commit
5176636f6d
2 changed files with 652 additions and 0 deletions
347
docs/deployment.md
Normal file
347
docs/deployment.md
Normal file
|
|
@ -0,0 +1,347 @@
|
|||
# Great Lakes Ice Report - Deployment Guide
|
||||
|
||||
This guide covers both automated and manual deployment options for the Great Lakes Ice Report application.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- **Server**: Debian 12 ARM64 (or compatible Linux distribution)
|
||||
- **Node.js**: Version 18 or higher
|
||||
- **Domain**: DNS pointing to your server
|
||||
- **Ports**: 80 and 443 open for web traffic
|
||||
|
||||
## Automated Deployment (Recommended)
|
||||
|
||||
### Quick Start
|
||||
|
||||
1. **Run the deployment script on your server:**
|
||||
```bash
|
||||
curl -sSL https://ice-puremichigan-lol.s3.amazonaws.com/scripts/deploy.sh | bash
|
||||
```
|
||||
|
||||
2. **Clone and setup the application:**
|
||||
```bash
|
||||
git clone git@git.deco.sh:deco/ice.git /opt/ice
|
||||
cd /opt/ice
|
||||
npm install # This automatically builds CSS via postinstall
|
||||
```
|
||||
|
||||
3. **Configure environment variables:**
|
||||
```bash
|
||||
cp .env.example .env
|
||||
nano .env # Add your API keys
|
||||
```
|
||||
|
||||
4. **Start services:**
|
||||
```bash
|
||||
sudo systemctl enable ice
|
||||
sudo systemctl start ice
|
||||
sudo systemctl enable caddy
|
||||
sudo systemctl start caddy
|
||||
```
|
||||
|
||||
### What the Automated Script Does
|
||||
|
||||
The deployment script automatically:
|
||||
|
||||
1. **System Updates**: Updates package repositories and system packages
|
||||
2. **Node.js Installation**: Installs Node.js 20.x with build tools
|
||||
3. **Go Installation**: Installs Go (required for building Caddy with plugins)
|
||||
4. **Custom Caddy Build**: Builds Caddy with rate limiting plugin using xcaddy
|
||||
5. **Service Configuration**: Creates systemd services for both the app and Caddy
|
||||
6. **Security Setup**: Configures users, permissions, and security settings
|
||||
|
||||
## Manual Deployment
|
||||
|
||||
### 1. System Preparation
|
||||
|
||||
```bash
|
||||
# Update system
|
||||
sudo apt update && sudo apt upgrade -y
|
||||
|
||||
# Install Node.js 20.x
|
||||
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
|
||||
sudo apt install -y nodejs build-essential
|
||||
|
||||
# Install Git (if not already installed)
|
||||
sudo apt install -y git
|
||||
```
|
||||
|
||||
### 2. Install Go (for Custom Caddy)
|
||||
|
||||
```bash
|
||||
# Download and install Go
|
||||
wget -q https://go.dev/dl/go1.21.5.linux-arm64.tar.gz
|
||||
sudo rm -rf /usr/local/go
|
||||
sudo tar -C /usr/local -xzf go1.21.5.linux-arm64.tar.gz
|
||||
|
||||
# Add to PATH
|
||||
export PATH=$PATH:/usr/local/go/bin
|
||||
echo 'export PATH=$PATH:/usr/local/go/bin' >> ~/.bashrc
|
||||
source ~/.bashrc
|
||||
```
|
||||
|
||||
### 3. Build Custom Caddy with Rate Limiting
|
||||
|
||||
```bash
|
||||
# Install xcaddy
|
||||
go install github.com/caddyserver/xcaddy/cmd/xcaddy@latest
|
||||
export PATH=$PATH:$(go env GOPATH)/bin
|
||||
|
||||
# Build Caddy with rate limiting plugin
|
||||
xcaddy build --with github.com/mholt/caddy-ratelimit
|
||||
|
||||
# Install Caddy
|
||||
sudo mv caddy /usr/local/bin/caddy
|
||||
sudo chmod +x /usr/local/bin/caddy
|
||||
```
|
||||
|
||||
### 4. Create Users and Directories
|
||||
|
||||
```bash
|
||||
# Create Caddy user
|
||||
sudo groupadd --system caddy
|
||||
sudo useradd --system --gid caddy --create-home --home-dir /var/lib/caddy --shell /usr/sbin/nologin caddy
|
||||
|
||||
# Create directories
|
||||
sudo mkdir -p /etc/caddy /var/log/caddy
|
||||
sudo chown -R caddy:caddy /var/log/caddy
|
||||
|
||||
# Create app user
|
||||
sudo groupadd --system great-lakes-ice-report
|
||||
sudo useradd --system --gid great-lakes-ice-report --create-home --home-dir /opt/great-lakes-ice-report --shell /usr/sbin/nologin great-lakes-ice-report
|
||||
```
|
||||
|
||||
### 5. Deploy Application
|
||||
|
||||
```bash
|
||||
# Clone repository
|
||||
sudo git clone https://github.com/your-username/ice.git /opt/great-lakes-ice-report
|
||||
cd /opt/great-lakes-ice-report
|
||||
|
||||
# Install dependencies and build
|
||||
sudo npm install
|
||||
sudo npm run build
|
||||
|
||||
# Set ownership
|
||||
sudo chown -R great-lakes-ice-report:great-lakes-ice-report /opt/great-lakes-ice-report
|
||||
```
|
||||
|
||||
### 6. Configure Environment
|
||||
|
||||
```bash
|
||||
# Copy environment template
|
||||
sudo cp .env.example .env
|
||||
|
||||
# Edit environment file
|
||||
sudo nano .env
|
||||
```
|
||||
|
||||
**Required environment variables:**
|
||||
```bash
|
||||
# MapBox API token (get free token at https://account.mapbox.com/access-tokens/)
|
||||
MAPBOX_ACCESS_TOKEN=pk.your_mapbox_token_here
|
||||
|
||||
# Admin panel password
|
||||
ADMIN_PASSWORD=your_secure_password
|
||||
|
||||
# Server port (default: 3000)
|
||||
PORT=3000
|
||||
|
||||
# Node environment
|
||||
NODE_ENV=production
|
||||
```
|
||||
|
||||
### 7. Configure Systemd Services
|
||||
|
||||
**Create app service:**
|
||||
```bash
|
||||
sudo cp scripts/great-lakes-ice-report.service /etc/systemd/system/
|
||||
```
|
||||
|
||||
**Create Caddy service:**
|
||||
```bash
|
||||
sudo tee /etc/systemd/system/caddy.service > /dev/null <<EOF
|
||||
[Unit]
|
||||
Description=Caddy
|
||||
Documentation=https://caddyserver.com/docs/
|
||||
After=network.target network-online.target
|
||||
Requires=network-online.target
|
||||
|
||||
[Service]
|
||||
Type=notify
|
||||
User=caddy
|
||||
Group=caddy
|
||||
ExecStart=/usr/local/bin/caddy run --environ --config /etc/caddy/Caddyfile
|
||||
ExecReload=/usr/local/bin/caddy reload --config /etc/caddy/Caddyfile --force
|
||||
TimeoutStopSec=5s
|
||||
LimitNOFILE=1048576
|
||||
LimitNPROC=1048576
|
||||
PrivateTmp=true
|
||||
ProtectSystem=full
|
||||
AmbientCapabilities=CAP_NET_BIND_SERVICE
|
||||
|
||||
[Install]
|
||||
WantedBy=multi-user.target
|
||||
EOF
|
||||
```
|
||||
|
||||
### 8. Configure Caddy
|
||||
|
||||
```bash
|
||||
# Copy Caddyfile
|
||||
sudo cp scripts/Caddyfile /etc/caddy/
|
||||
|
||||
# Edit domain name in Caddyfile
|
||||
sudo nano /etc/caddy/Caddyfile
|
||||
# Change 'ice.puremichigan.lol' to your domain
|
||||
```
|
||||
|
||||
### 9. Start Services
|
||||
|
||||
```bash
|
||||
# Reload systemd
|
||||
sudo systemctl daemon-reload
|
||||
|
||||
# Enable and start services
|
||||
sudo systemctl enable great-lakes-ice-report
|
||||
sudo systemctl start great-lakes-ice-report
|
||||
|
||||
sudo systemctl enable caddy
|
||||
sudo systemctl start caddy
|
||||
```
|
||||
|
||||
## Security Configuration
|
||||
|
||||
### Firewall Setup
|
||||
|
||||
```bash
|
||||
# Install UFW if not present
|
||||
sudo apt install -y ufw
|
||||
|
||||
# Configure firewall
|
||||
sudo ufw default deny incoming
|
||||
sudo ufw default allow outgoing
|
||||
sudo ufw allow ssh
|
||||
sudo ufw allow 80/tcp
|
||||
sudo ufw allow 443/tcp
|
||||
sudo ufw --force enable
|
||||
```
|
||||
|
||||
### SSL Certificates
|
||||
|
||||
Caddy automatically obtains SSL certificates from Let's Encrypt. No manual configuration required.
|
||||
|
||||
### Rate Limiting
|
||||
|
||||
The application includes multiple layers of rate limiting:
|
||||
|
||||
1. **Application Level**: 10 requests per 15 minutes per IP for location submissions
|
||||
2. **Caddy Level**:
|
||||
- 30 requests per minute for general API endpoints
|
||||
- 5 requests per minute for location submissions
|
||||
|
||||
## Monitoring and Maintenance
|
||||
|
||||
### Service Status
|
||||
|
||||
```bash
|
||||
# Check application status
|
||||
sudo systemctl status great-lakes-ice-report
|
||||
|
||||
# Check Caddy status
|
||||
sudo systemctl status caddy
|
||||
|
||||
# View logs
|
||||
sudo journalctl -u great-lakes-ice-report -f
|
||||
sudo journalctl -u caddy -f
|
||||
```
|
||||
|
||||
### Log Files
|
||||
|
||||
- **Application logs**: `sudo journalctl -u great-lakes-ice-report`
|
||||
- **Caddy access logs**: `/var/log/caddy/great-lakes-ice-report.log`
|
||||
- **System logs**: `/var/log/syslog`
|
||||
|
||||
### Database Maintenance
|
||||
|
||||
The application automatically:
|
||||
- Cleans up expired location reports (older than 48 hours)
|
||||
- Maintains profanity filter database
|
||||
- Uses SQLite with automatic cleanup
|
||||
|
||||
### Updates
|
||||
|
||||
```bash
|
||||
# Navigate to app directory
|
||||
cd /opt/great-lakes-ice-report
|
||||
|
||||
# Pull latest changes
|
||||
sudo git pull
|
||||
|
||||
# Install new dependencies
|
||||
sudo npm install
|
||||
|
||||
# Rebuild application
|
||||
sudo npm run build
|
||||
|
||||
# Restart service
|
||||
sudo systemctl restart great-lakes-ice-report
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Common Issues
|
||||
|
||||
1. **Service won't start**:
|
||||
```bash
|
||||
sudo journalctl -u great-lakes-ice-report --no-pager
|
||||
```
|
||||
|
||||
2. **SSL certificate issues**:
|
||||
```bash
|
||||
sudo journalctl -u caddy --no-pager
|
||||
```
|
||||
|
||||
3. **Database permissions**:
|
||||
```bash
|
||||
sudo chown -R great-lakes-ice-report:great-lakes-ice-report /opt/great-lakes-ice-report
|
||||
```
|
||||
|
||||
4. **Port conflicts**:
|
||||
```bash
|
||||
sudo netstat -tlnp | grep :3000
|
||||
sudo netstat -tlnp | grep :80
|
||||
sudo netstat -tlnp | grep :443
|
||||
```
|
||||
|
||||
### Performance Tuning
|
||||
|
||||
For high-traffic deployments:
|
||||
|
||||
1. **Increase Node.js memory limit**:
|
||||
```bash
|
||||
# Edit service file
|
||||
sudo nano /etc/systemd/system/great-lakes-ice-report.service
|
||||
# Add: Environment=NODE_OPTIONS="--max-old-space-size=4096"
|
||||
```
|
||||
|
||||
2. **Configure log rotation**:
|
||||
```bash
|
||||
sudo nano /etc/logrotate.d/great-lakes-ice-report
|
||||
```
|
||||
|
||||
3. **Monitor resource usage**:
|
||||
```bash
|
||||
htop
|
||||
sudo iotop
|
||||
```
|
||||
|
||||
## Support
|
||||
|
||||
For deployment issues:
|
||||
- Check system logs: `sudo journalctl -f`
|
||||
- Verify environment variables: `sudo -u great-lakes-ice-report env`
|
||||
- Test application directly: `cd /opt/great-lakes-ice-report && sudo -u great-lakes-ice-report node server.js`
|
||||
- Review this documentation and configuration files
|
||||
|
||||
The application includes comprehensive logging and monitoring to help diagnose issues quickly.
|
||||
Loading…
Add table
Add a link
Reference in a new issue