Merge pull request 'Fix deployment documentation for TypeScript setup' (#16) from fix/deployment-documentation into main

Reviewed-on: deco/ice#16

README.md

@@ -111,6 +111,10 @@ PORT=3000
 
 ## Deployment
 
+### Quick Deployment (Recommended)
+
+See `docs/deployment-quickstart.md` for a simplified deployment guide.
+
 ### Automated Deployment (Debian 12 ARM64)
 
 1. **Run the deployment script on your server:**
@@ -120,9 +124,11 @@ PORT=3000
 
 2. **Deploy your application:**
    ```bash
-   git clone git@git.deco.sh:deco/ice.git /opt/ice
+   sudo git clone https://git.deco.sh/deco/ice.git /opt/icewatch
-   cd /opt/ice
+   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:**
@@ -131,10 +137,16 @@ PORT=3000
    nano .env  # Add your API keys
    ```
 
-4. **Start services:**
+4. **Create databases and set permissions:**
    ```bash
-   sudo systemctl enable ice
+   touch icewatch.db profanity.db
-   sudo systemctl start ice
+   sudo chown -R icewatch:icewatch /opt/icewatch
+   ```
+
+5. **Start services:**
+   ```bash
+   sudo systemctl enable icewatch
+   sudo systemctl start icewatch
    sudo systemctl enable caddy
    sudo systemctl start caddy
    ```

docs/deployment-quickstart.md

@@ -0,0 +1,164 @@
+# 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
+
+```bash
+# Clone the repository
+sudo git clone https://git.deco.sh/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
+
+```bash
+# 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
+
+```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
+
+```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
+```
+
+## Updating the Application
+
+```bash
+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
+```bash
+# 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
+```bash
+# Ensure databases exist and have correct permissions
+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
+```
+
+## 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

docs/deployment.md

@@ -20,9 +20,11 @@ This guide covers both automated and manual deployment options for the Great Lak
 
 2. **Clone and setup the application:**
    ```bash
-   git clone git@git.deco.sh:deco/ice.git /opt/ice
+   sudo git clone https://git.deco.sh/deco/ice.git /opt/icewatch
-   cd /opt/ice
+   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:**
@@ -33,8 +35,8 @@ This guide covers both automated and manual deployment options for the Great Lak
 
 4. **Start services:**
    ```bash
-   sudo systemctl enable ice
+   sudo systemctl enable icewatch
-   sudo systemctl start ice
+   sudo systemctl start icewatch
    sudo systemctl enable caddy
    sudo systemctl start caddy
    ```
@@ -64,6 +66,9 @@ sudo apt install -y nodejs build-essential
 
 # Install Git (if not already installed)
 sudo apt install -y git
+
+# Verify Node.js version (should be 18+ for TypeScript)
+node --version
 ```
 
 ### 2. Install Go (for Custom Caddy)
@@ -107,23 +112,29 @@ 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 groupadd --system icewatch
-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
+sudo useradd --system --gid icewatch --create-home --home-dir /opt/icewatch --shell /usr/sbin/nologin icewatch
 ```
 
 ### 5. Deploy Application
 
 ```bash
 # Clone repository
-sudo git clone https://github.com/your-username/ice.git /opt/great-lakes-ice-report
+sudo git clone https://git.deco.sh/deco/ice.git /opt/icewatch
-cd /opt/great-lakes-ice-report
+cd /opt/icewatch
+
+# Set temporary ownership for installation
+sudo chown -R $USER:$USER /opt/icewatch
 
 # Install dependencies and build
-sudo npm install
+npm install  # This automatically builds CSS
-sudo npm run build
+npm run build:ts  # Compile TypeScript to JavaScript
 
-# Set ownership
+# Create databases
-sudo chown -R great-lakes-ice-report:great-lakes-ice-report /opt/great-lakes-ice-report
+touch icewatch.db profanity.db
+
+# Set final ownership
+sudo chown -R icewatch:icewatch /opt/icewatch
 ```
 
 ### 6. Configure Environment
@@ -155,7 +166,9 @@ NODE_ENV=production
 
 **Create app service:**
 ```bash
-sudo cp scripts/great-lakes-ice-report.service /etc/systemd/system/
+sudo cp scripts/icewatch.service /etc/systemd/system/
+# Ensure the service file has the correct ExecStart:
+# ExecStart=/usr/bin/node dist/server.js
 ```
 
 **Create Caddy service:**
@@ -203,8 +216,8 @@ sudo nano /etc/caddy/Caddyfile
 sudo systemctl daemon-reload
 
 # Enable and start services
-sudo systemctl enable great-lakes-ice-report
+sudo systemctl enable icewatch
-sudo systemctl start great-lakes-ice-report
+sudo systemctl start icewatch
 
 sudo systemctl enable caddy
 sudo systemctl start caddy
@@ -246,19 +259,19 @@ The application includes multiple layers of rate limiting:
 
 ```bash
 # Check application status
-sudo systemctl status great-lakes-ice-report
+sudo systemctl status icewatch
 
 # Check Caddy status
 sudo systemctl status caddy
 
 # View logs
-sudo journalctl -u great-lakes-ice-report -f
+sudo journalctl -u icewatch -f
 sudo journalctl -u caddy -f
 ```
 
 ### Log Files
 
-- **Application logs**: `sudo journalctl -u great-lakes-ice-report`
+- **Application logs**: `sudo journalctl -u icewatch`
 - **Caddy access logs**: `/var/log/caddy/great-lakes-ice-report.log`
 - **System logs**: `/var/log/syslog`
 
@@ -273,19 +286,20 @@ The application automatically:
 
 ```bash
 # Navigate to app directory
-cd /opt/great-lakes-ice-report
+cd /opt/icewatch
+
+# Stop the service
+sudo systemctl stop icewatch
 
 # Pull latest changes
-sudo git pull
+sudo -u icewatch git pull
 
-# Install new dependencies
+# Install new dependencies and rebuild
-sudo npm install
+sudo -u icewatch npm install
-
+sudo -u icewatch npm run build:ts
-# Rebuild application
-sudo npm run build
 
 # Restart service
-sudo systemctl restart great-lakes-ice-report
+sudo systemctl restart icewatch
 ```
 
 ## Troubleshooting
@@ -294,7 +308,7 @@ sudo systemctl restart great-lakes-ice-report
 
 1. **Service won't start**:
    ```bash
-   sudo journalctl -u great-lakes-ice-report --no-pager
+   sudo journalctl -u icewatch --no-pager
    ```
 
 2. **SSL certificate issues**:
@@ -304,7 +318,13 @@ sudo systemctl restart great-lakes-ice-report
 
 3. **Database permissions**:
    ```bash
-   sudo chown -R great-lakes-ice-report:great-lakes-ice-report /opt/great-lakes-ice-report
+   sudo chown -R icewatch:icewatch /opt/icewatch
+   ```
+
+4. **TypeScript compilation issues**:
+   ```bash
+   cd /opt/icewatch
+   sudo -u icewatch npm run build:ts
    ```
 
 4. **Port conflicts**:
@@ -321,7 +341,7 @@ For high-traffic deployments:
 1. **Increase Node.js memory limit**:
    ```bash
    # Edit service file
-   sudo nano /etc/systemd/system/great-lakes-ice-report.service
+   sudo nano /etc/systemd/system/icewatch.service
    # Add: Environment=NODE_OPTIONS="--max-old-space-size=4096"
    ```
 
@@ -340,8 +360,9 @@ For high-traffic deployments:
 
 For deployment issues:
 - Check system logs: `sudo journalctl -f`
-- Verify environment variables: `sudo -u great-lakes-ice-report env`
+- Verify environment variables: `sudo -u icewatch env`
-- Test application directly: `cd /opt/great-lakes-ice-report && sudo -u great-lakes-ice-report node server.js`
+- 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`
 
 The application includes comprehensive logging and monitoring to help diagnose issues quickly.

scripts/icewatch.service

@@ -1,5 +1,5 @@
 [Unit]
-Description=ICE Watch Michigan - Community Safety Tool
+Description=Great Lakes Ice Report - Community Safety Tool
 After=network.target
 Wants=network.target
 
@@ -8,7 +8,7 @@ Type=simple
 User=icewatch
 Group=icewatch
 WorkingDirectory=/opt/icewatch
-ExecStart=/usr/bin/node server.js
+ExecStart=/usr/bin/node dist/server.js
 Restart=always
 RestartSec=5
 Environment=NODE_ENV=production

src/swagger.ts

@@ -21,7 +21,7 @@ const options: swaggerJsdoc.Options = {
       `,
       contact: {
         name: 'Great Lakes Ice Report',
-        url: 'https://github.com/deco/ice'
+        url: 'https://git.deco.sh/deco/ice'
       },
       license: {
         name: 'MIT',