diff --git a/README.md b/README.md index 30633bd..bf853b6 100644 --- a/README.md +++ b/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 - cd /opt/ice + sudo git clone https://git.deco.sh/deco/ice.git /opt/icewatch + 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 - sudo systemctl start ice + touch icewatch.db profanity.db + 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 ``` diff --git a/docs/deployment-quickstart.md b/docs/deployment-quickstart.md new file mode 100644 index 0000000..3e903e2 --- /dev/null +++ b/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 \ No newline at end of file diff --git a/docs/deployment.md b/docs/deployment.md index 7b25216..768f116 100644 --- a/docs/deployment.md +++ b/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 - cd /opt/ice + sudo git clone https://git.deco.sh/deco/ice.git /opt/icewatch + 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 start ice + sudo systemctl enable icewatch + 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 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 groupadd --system icewatch +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 -cd /opt/great-lakes-ice-report +sudo git clone https://git.deco.sh/deco/ice.git /opt/icewatch +cd /opt/icewatch + +# Set temporary ownership for installation +sudo chown -R $USER:$USER /opt/icewatch # Install dependencies and build -sudo npm install -sudo npm run build +npm install # This automatically builds CSS +npm run build:ts # Compile TypeScript to JavaScript -# Set ownership -sudo chown -R great-lakes-ice-report:great-lakes-ice-report /opt/great-lakes-ice-report +# Create databases +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 start great-lakes-ice-report +sudo systemctl enable icewatch +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 -sudo npm install - -# Rebuild application -sudo npm run build +# Install new dependencies and rebuild +sudo -u icewatch npm install +sudo -u icewatch npm run build:ts # 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` -- Test application directly: `cd /opt/great-lakes-ice-report && sudo -u great-lakes-ice-report node server.js` +- 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` The application includes comprehensive logging and monitoring to help diagnose issues quickly. \ No newline at end of file diff --git a/scripts/icewatch.service b/scripts/icewatch.service index a618528..7c54af8 100644 --- a/scripts/icewatch.service +++ b/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 diff --git a/src/swagger.ts b/src/swagger.ts index 67279db..fce3c2e 100644 --- a/src/swagger.ts +++ b/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',