signal-works/ice
1
0
Fork 0
Code Issues Pull requests 1 Projects Releases Packages Wiki Activity Actions

Sync all deployment documentation and remove manual database creation

Browse source 
- 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 <noreply@anthropic.com>
This commit is contained in:
Claude Code 2025-07-06 18:37:48 -04:00
parent e2b3593c37
commit c395183158
3 changed files with 138 additions and 140 deletions
Download patch file Download diff file Expand all files Collapse all files

178
docs/deployment-quickstart.md
View file

@ -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
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

91
docs/deployment.md
View file

@ -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.

9
scripts/deploy.sh
View file

@ -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 ""