Merge pull request 'Fix deployment documentation for TypeScript setup' (#16) from fix/deployment-documentation into main
Reviewed-on: deco/ice#16
This commit is contained in:
commit
ea870dd91f
5 changed files with 236 additions and 39 deletions
22
README.md
22
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
|
||||
```
|
||||
|
|
|
|||
164
docs/deployment-quickstart.md
Normal file
164
docs/deployment-quickstart.md
Normal file
|
|
@ -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
|
||||
|
|
@ -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.
|
||||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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',
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue