From c395183158a675c05c2f6187af04a1dcd37eb9cb Mon Sep 17 00:00:00 2001 From: Claude Code Date: Sun, 6 Jul 2025 18:37:48 -0400 Subject: [PATCH] Sync all deployment documentation and remove manual database creation MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Align deploy.sh, deployment.md, and deployment-quickstart.md with consistent steps - Remove manual database file creation (SQLite creates them automatically) - Update all documents to use npm run build instead of npm run build:ts - Add architecture support for both ARM64 and x86_64 - Include S3_BUCKET_NAME=none option for local-only deployment - Fix step numbering after removing database creation step 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude --- docs/deployment-quickstart.md | 178 ++++++++++++++-------------------- docs/deployment.md | 91 +++++++++++------ scripts/deploy.sh | 9 +- 3 files changed, 138 insertions(+), 140 deletions(-) diff --git a/docs/deployment-quickstart.md b/docs/deployment-quickstart.md index 3e903e2..fc64591 100644 --- a/docs/deployment-quickstart.md +++ b/docs/deployment-quickstart.md @@ -1,113 +1,88 @@ # Great Lakes Ice Report - Quick Deployment Guide -This is a simplified deployment guide for quickly setting up the Great Lakes Ice Report application at `/opt/icewatch`. +This is a simplified deployment guide for quickly setting up the Great Lakes Ice Report application. ## Prerequisites -- Debian 12 ARM64 server (or compatible Linux) -- Node.js 18+ installed -- Domain pointing to your server +- Debian 12 (ARM64 or x86_64) server - Root or sudo access +- Domain pointing to your server (optional, defaults to ice.puremichigan.lol) -## Step 1: Clone and Build +## Quick Start - Automated Deployment ```bash -# Clone the repository -sudo git clone https://git.deco.sh/deco/ice.git /opt/icewatch +# Run the automated deployment script +curl -sSL https://ice-puremichigan-lol.s3.amazonaws.com/scripts/deploy.sh | bash + +# Or to use local files only (no S3) +curl -sSL https://ice-puremichigan-lol.s3.amazonaws.com/scripts/deploy.sh | S3_BUCKET_NAME=none bash +``` + +Then follow the instructions printed by the script. The key steps are: + +## Manual Steps After Running Deployment Script + +### 1. Clone the Repository +```bash +git clone https://git.deco.sh/deco/ice.git /opt/icewatch +``` + +### 2. Copy Configuration Files (if using S3_BUCKET_NAME=none) +```bash +sudo cp /opt/icewatch/scripts/icewatch.service /etc/systemd/system/ +sudo cp /opt/icewatch/scripts/Caddyfile /etc/caddy/Caddyfile +``` + +### 3. Set Up the Application +```bash cd /opt/icewatch - -# Set temporary ownership for build -sudo chown -R $USER:$USER /opt/icewatch - -# Install dependencies (this also builds CSS) npm install - -# Build TypeScript to JavaScript -npm run build:ts - -# Create database files -touch icewatch.db profanity.db -``` - -## Step 2: Configure Environment - -```bash -# Copy environment template +npm run build # Compile TypeScript and build CSS cp .env.example .env - -# Edit with your settings -nano .env +nano .env # Add your MapBox token and admin password ``` -Required settings: +### 4. Configure Domain (if needed) +```bash +sudo nano /etc/caddy/Caddyfile +# Change 'ice.puremichigan.lol' to your domain +``` + +### 5. Set Permissions +```bash +sudo chown -R icewatch:icewatch /opt/icewatch +sudo chmod 660 /opt/icewatch/.env +``` + +### 6. Start Services +```bash +sudo systemctl daemon-reload +sudo systemctl enable icewatch caddy +sudo systemctl start icewatch caddy +``` + +### 7. Check Status +```bash +sudo systemctl status icewatch +sudo systemctl status caddy +``` + +## Environment Variables + +Edit `.env` with these required settings: ``` MAPBOX_ACCESS_TOKEN=pk.your_mapbox_token_here ADMIN_PASSWORD=your_secure_password PORT=3000 +NODE_ENV=production ``` -## Step 3: Create System User - -```bash -# Create icewatch user with bash shell for easier management -sudo useradd --system --shell /bin/bash --home /opt/icewatch icewatch - -# Set ownership -sudo chown -R icewatch:icewatch /opt/icewatch - -# Now you can switch to the icewatch user when needed: -# sudo -u icewatch -i -# or -# sudo su - icewatch -``` - -## Step 4: Install Systemd Service - -```bash -# Copy service file -sudo cp scripts/icewatch.service /etc/systemd/system/ - -# Reload systemd -sudo systemctl daemon-reload - -# Enable and start service -sudo systemctl enable icewatch -sudo systemctl start icewatch - -# Check status -sudo systemctl status icewatch -``` - -## Step 5: Install and Configure Caddy - -```bash -# Install Caddy (if not already installed) -sudo apt install -y debian-keyring debian-archive-keyring apt-transport-https -curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/gpg.key' | sudo gpg --dearmor -o /usr/share/keyrings/caddy-stable-archive-keyring.gpg -curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/debian.deb.txt' | sudo tee /etc/apt/sources.list.d/caddy-stable.list -sudo apt update -sudo apt install caddy - -# Copy Caddyfile -sudo cp scripts/Caddyfile /etc/caddy/Caddyfile - -# Edit domain in Caddyfile -sudo nano /etc/caddy/Caddyfile -# Change 'ice.puremichigan.lol' to your domain - -# Restart Caddy -sudo systemctl restart caddy -``` - -## Step 6: Verify Installation +## Verify Installation ```bash # Test locally curl http://localhost:3000/api/locations -# Test the /table route -curl http://localhost:3000/table - # Check logs if needed sudo journalctl -u icewatch -f ``` @@ -118,12 +93,12 @@ sudo journalctl -u icewatch -f cd /opt/icewatch sudo systemctl stop icewatch -# Pull latest changes +# Pull latest changes as icewatch user sudo -u icewatch git pull # Install dependencies and rebuild sudo -u icewatch npm install -sudo -u icewatch npm run build:ts +sudo -u icewatch npm run build # Restart service sudo systemctl start icewatch @@ -136,29 +111,24 @@ sudo systemctl start icewatch # Check logs sudo journalctl -u icewatch --no-pager -n 50 -# Run manually to see errors +# Common issue: Missing dist/server.js cd /opt/icewatch -sudo -u icewatch node dist/server.js +npm run build + +# Database files are created automatically by the application ``` -### Database errors +### Permission errors ```bash -# Ensure databases exist and have correct permissions +# Ensure correct ownership of project directory cd /opt/icewatch -ls -la *.db -sudo chown icewatch:icewatch *.db -``` - -### TypeScript not compiled -```bash -cd /opt/icewatch -sudo -u icewatch npm run build:ts +sudo chown -R icewatch:icewatch /opt/icewatch ``` ## Important Notes -1. The application uses TypeScript which compiles to `dist/` directory -2. The systemd service runs `dist/server.js` (the compiled output) -3. Always run `npm run build:ts` after pulling updates -4. The `/table` route provides a non-JavaScript fallback view -5. Database files (`icewatch.db` and `profanity.db`) must exist in the root directory \ No newline at end of file +1. The deployment script installs Node.js, Go, and builds a custom Caddy with rate limiting +2. The application uses TypeScript which must be compiled with `npm run build` +3. Database files are created automatically by the application +4. The service runs as the `icewatch` system user +5. Caddy automatically obtains SSL certificates \ No newline at end of file diff --git a/docs/deployment.md b/docs/deployment.md index 768f116..344c9d4 100644 --- a/docs/deployment.md +++ b/docs/deployment.md @@ -4,9 +4,9 @@ This guide covers both automated and manual deployment options for the Great Lak ## Prerequisites -- **Server**: Debian 12 ARM64 (or compatible Linux distribution) -- **Node.js**: Version 18 or higher -- **Domain**: DNS pointing to your server +- **Server**: Debian 12 (ARM64 or x86_64) +- **Access**: Root or sudo access +- **Domain**: DNS pointing to your server (optional) - **Ports**: 80 and 443 open for web traffic ## Automated Deployment (Recommended) @@ -15,30 +15,42 @@ This guide covers both automated and manual deployment options for the Great Lak 1. **Run the deployment script on your server:** ```bash + # Default: Downloads config from S3 curl -sSL https://ice-puremichigan-lol.s3.amazonaws.com/scripts/deploy.sh | bash + + # Alternative: Use local files only (no S3) + curl -sSL https://ice-puremichigan-lol.s3.amazonaws.com/scripts/deploy.sh | S3_BUCKET_NAME=none bash ``` -2. **Clone and setup the application:** +2. **Follow the printed instructions from the script:** ```bash - sudo git clone https://git.deco.sh/deco/ice.git /opt/icewatch + # Clone repository + git clone https://git.deco.sh/deco/ice.git /opt/icewatch + + # Copy config files (only if using S3_BUCKET_NAME=none) + sudo cp /opt/icewatch/scripts/icewatch.service /etc/systemd/system/ + sudo cp /opt/icewatch/scripts/Caddyfile /etc/caddy/Caddyfile + + # Set up application cd /opt/icewatch - sudo chown -R $USER:$USER /opt/icewatch - npm install # This automatically builds CSS via postinstall - npm run build:ts # Compile TypeScript to JavaScript - ``` - -3. **Configure environment variables:** - ```bash + npm install + npm run build # Compile TypeScript and build CSS cp .env.example .env - nano .env # Add your API keys - ``` - -4. **Start services:** - ```bash - sudo systemctl enable icewatch - sudo systemctl start icewatch - sudo systemctl enable caddy - sudo systemctl start caddy + nano .env # Add your MapBox token and admin password + + # Configure domain (if needed) + sudo nano /etc/caddy/Caddyfile + + # Database files are created automatically by the application + + # Set permissions + sudo chown -R icewatch:icewatch /opt/icewatch + sudo chmod 660 /opt/icewatch/.env + + # Start services + sudo systemctl daemon-reload + sudo systemctl enable icewatch caddy + sudo systemctl start icewatch caddy ``` ### What the Automated Script Does @@ -74,15 +86,35 @@ node --version ### 2. Install Go (for Custom Caddy) ```bash +# Architecture detection +ARCH=$(uname -m) +case $ARCH in + x86_64) + GO_ARCH="amd64" + ;; + aarch64|arm64) + GO_ARCH="arm64" + ;; + *) + echo "Unsupported architecture: $ARCH" + exit 1 + ;; +esac + # Download and install Go -wget -q https://go.dev/dl/go1.21.5.linux-arm64.tar.gz +GO_VERSION="1.21.5" +GO_TARBALL="go${GO_VERSION}.linux-${GO_ARCH}.tar.gz" +wget -q "https://go.dev/dl/${GO_TARBALL}" sudo rm -rf /usr/local/go -sudo tar -C /usr/local -xzf go1.21.5.linux-arm64.tar.gz +sudo tar -C /usr/local -xzf "${GO_TARBALL}" # Add to PATH export PATH=$PATH:/usr/local/go/bin echo 'export PATH=$PATH:/usr/local/go/bin' >> ~/.bashrc source ~/.bashrc + +# Clean up +rm -f "${GO_TARBALL}" ``` ### 3. Build Custom Caddy with Rate Limiting @@ -128,10 +160,9 @@ sudo chown -R $USER:$USER /opt/icewatch # Install dependencies and build npm install # This automatically builds CSS -npm run build:ts # Compile TypeScript to JavaScript +npm run build # Compile TypeScript and build CSS -# Create databases -touch icewatch.db profanity.db +# Database files are created automatically by the application # Set final ownership sudo chown -R icewatch:icewatch /opt/icewatch @@ -296,7 +327,7 @@ sudo -u icewatch git pull # Install new dependencies and rebuild sudo -u icewatch npm install -sudo -u icewatch npm run build:ts +sudo -u icewatch npm run build # Restart service sudo systemctl restart icewatch @@ -316,7 +347,7 @@ sudo systemctl restart icewatch sudo journalctl -u caddy --no-pager ``` -3. **Database permissions**: +3. **Permission issues**: ```bash sudo chown -R icewatch:icewatch /opt/icewatch ``` @@ -324,7 +355,7 @@ sudo systemctl restart icewatch 4. **TypeScript compilation issues**: ```bash cd /opt/icewatch - sudo -u icewatch npm run build:ts + sudo -u icewatch npm run build ``` 4. **Port conflicts**: @@ -363,6 +394,6 @@ For deployment issues: - Verify environment variables: `sudo -u icewatch env` - Test application directly: `cd /opt/icewatch && sudo -u icewatch node dist/server.js` - Review this documentation and configuration files -- Ensure TypeScript is compiled: `npm run build:ts` +- Ensure TypeScript is compiled: `npm run build` The application includes comprehensive logging and monitoring to help diagnose issues quickly. \ No newline at end of file diff --git a/scripts/deploy.sh b/scripts/deploy.sh index 4e8ebad..050da57 100644 --- a/scripts/deploy.sh +++ b/scripts/deploy.sh @@ -188,19 +188,16 @@ echo "4. Configure domain in Caddyfile (if needed):" echo " sudo nano /etc/caddy/Caddyfile" echo " # The default is configured for ice.puremichigan.lol" echo "" -echo "5. Create database files:" -echo " touch icewatch.db profanity.db" -echo "" -echo "6. Set permissions:" +echo "5. Set permissions:" echo " sudo chown -R icewatch:icewatch /opt/icewatch" echo " sudo chmod 660 /opt/icewatch/.env" echo "" -echo "7. Start services:" +echo "6. Start services:" echo " sudo systemctl daemon-reload" echo " sudo systemctl enable icewatch caddy" echo " sudo systemctl start icewatch caddy" echo "" -echo "8. Check status:" +echo "7. Check status:" echo " sudo systemctl status icewatch" echo " sudo systemctl status caddy" echo ""