ice/docs/deployment-quickstart.md

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.

Prerequisites

• Debian 12 ARM64 server (or compatible Linux)
• Node.js 18+ installed
• Domain pointing to your server
• Root or sudo access

Step 1: Clone and Build

# Clone the repository
sudo git clone https://github.com/deco/ice.git /opt/icewatch
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

# Copy environment template
cp .env.example .env

# Edit with your settings
nano .env

Required settings:

MAPBOX_ACCESS_TOKEN=pk.your_mapbox_token_here
ADMIN_PASSWORD=your_secure_password
PORT=3000

Step 3: Create System User

# 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

# 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

# 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

# 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

Updating the Application

cd /opt/icewatch
sudo systemctl stop icewatch

# Pull latest changes
sudo -u icewatch git pull

# Install dependencies and rebuild
sudo -u icewatch npm install
sudo -u icewatch npm run build:ts

# Restart service
sudo systemctl start icewatch

Troubleshooting

Service won't start

# Check logs
sudo journalctl -u icewatch --no-pager -n 50

# Run manually to see errors
cd /opt/icewatch
sudo -u icewatch node dist/server.js

Database errors

# Ensure databases exist and have correct permissions
cd /opt/icewatch
ls -la *.db
sudo chown icewatch:icewatch *.db

TypeScript not compiled

cd /opt/icewatch
sudo -u icewatch npm run build:ts

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