327 lines
6.3 KiB
Markdown
327 lines
6.3 KiB
Markdown
# jnss-web Static Site Deployment Guide
|
|
|
|
## Overview
|
|
|
|
This document describes the deployment process for jnss-web, a SvelteKit-based static website serving as the primary entrypoint for jnss.me.
|
|
|
|
## Architecture
|
|
|
|
- **Technology**: SvelteKit v2 with static adapter
|
|
- **Build Tool**: Bun
|
|
- **Deployment**: Ansible playbook with git-based artifact deployment
|
|
- **Web Server**: Caddy (direct file serving)
|
|
- **Repository**: git.jnss.me/joakim/jnss-web
|
|
- **Branch Strategy**:
|
|
- `main` - Source code
|
|
- `deploy` - Build artifacts only
|
|
|
|
## Server Architecture
|
|
|
|
```
|
|
/opt/jnss-web-repo/ # Git clone of deploy branch
|
|
/var/www/jnss-web/ # Synced build artifacts (served by Caddy)
|
|
/etc/caddy/sites-enabled/
|
|
└── jnss-web.caddy # Site config with www redirect
|
|
/var/log/caddy/jnss-web.log # Access logs
|
|
```
|
|
|
|
## Development Workflow
|
|
|
|
### 1. Local Development (main branch)
|
|
|
|
```bash
|
|
cd ~/dev/jnss-web
|
|
git checkout main
|
|
|
|
# Make changes to source code
|
|
# ...
|
|
|
|
# Test locally
|
|
bun run dev
|
|
|
|
# Build to verify
|
|
bun run build
|
|
```
|
|
|
|
### 2. Prepare Deploy Branch
|
|
|
|
```bash
|
|
# Build production version
|
|
bun run build
|
|
|
|
# Switch to deploy branch
|
|
git checkout deploy
|
|
|
|
# Merge changes from main
|
|
git merge main --no-commit
|
|
|
|
# Rebuild to ensure fresh build
|
|
bun run build
|
|
|
|
# Add only build artifacts
|
|
git add build/
|
|
|
|
# Commit with descriptive message
|
|
git commit -m "Deploy: Add new feature X"
|
|
|
|
# Push to Gitea
|
|
git push origin deploy
|
|
```
|
|
|
|
### 3. Deploy to Server
|
|
|
|
```bash
|
|
cd ~/rick-infra
|
|
|
|
# Run deployment playbook
|
|
ansible-playbook -i inventory/hosts.yml playbooks/deploy-jnss-web.yml
|
|
|
|
# Watch logs (optional)
|
|
ssh root@arch-vps 'tail -f /var/log/caddy/jnss-web.log'
|
|
```
|
|
|
|
## Playbook Details
|
|
|
|
### Variables
|
|
|
|
Located in `playbooks/deploy-jnss-web.yml`:
|
|
|
|
- `jnss_web_repo_owner`: Your Gitea username (default: "joakim")
|
|
- `jnss_web_branch`: Branch to deploy (default: "deploy")
|
|
- `jnss_web_domain`: Primary domain (default: "jnss.me")
|
|
|
|
### Tags
|
|
|
|
- `jnss-web` - All jnss-web tasks
|
|
- `deploy` - Git clone/sync tasks
|
|
- `caddy` - Caddy configuration tasks
|
|
|
|
### Example Usage
|
|
|
|
```bash
|
|
# Full deployment
|
|
ansible-playbook -i inventory/hosts.yml playbooks/deploy-jnss-web.yml
|
|
|
|
# Only update Caddy config (no git pull)
|
|
ansible-playbook -i inventory/hosts.yml playbooks/deploy-jnss-web.yml --tags caddy
|
|
|
|
# Only sync files (skip Caddy reload)
|
|
ansible-playbook -i inventory/hosts.yml playbooks/deploy-jnss-web.yml --tags deploy
|
|
```
|
|
|
|
## Initial Setup
|
|
|
|
### jnss-web Project Configuration
|
|
|
|
The following changes need to be made in the jnss-web project:
|
|
|
|
#### 1. Install Static Adapter
|
|
|
|
```bash
|
|
cd ~/dev/jnss-web
|
|
bun add -D @sveltejs/adapter-static
|
|
```
|
|
|
|
#### 2. Update svelte.config.js
|
|
|
|
```javascript
|
|
import adapter from '@sveltejs/adapter-static';
|
|
|
|
/** @type {import('@sveltejs/kit').Config} */
|
|
const config = {
|
|
kit: {
|
|
adapter: adapter({
|
|
pages: 'build',
|
|
assets: 'build',
|
|
fallback: undefined,
|
|
precompress: false,
|
|
strict: true
|
|
})
|
|
}
|
|
};
|
|
|
|
export default config;
|
|
```
|
|
|
|
#### 3. Create src/routes/+layout.js
|
|
|
|
```javascript
|
|
export const prerender = true;
|
|
```
|
|
|
|
#### 4. Update .gitignore
|
|
|
|
Comment out or remove the build directory from .gitignore:
|
|
|
|
```gitignore
|
|
# build/ <- Comment this out or remove it
|
|
```
|
|
|
|
#### 5. Create Deploy Branch
|
|
|
|
```bash
|
|
# Build the site first
|
|
bun run build
|
|
|
|
# Create and switch to deploy branch
|
|
git checkout -b deploy
|
|
|
|
# Remove source files (keep only build artifacts)
|
|
git rm -r src static *.config.js package.json bun.lock jsconfig.json .npmrc
|
|
|
|
# Keep only build/ and documentation
|
|
git add build/ README.md
|
|
|
|
# Commit
|
|
git commit -m "Initial deploy branch with build artifacts"
|
|
|
|
# Push to Gitea
|
|
git push -u origin deploy
|
|
|
|
# Switch back to main
|
|
git checkout main
|
|
```
|
|
|
|
## Troubleshooting
|
|
|
|
### Build Directory Not Found
|
|
|
|
**Error**: "Build directory not found in repository"
|
|
|
|
**Solution**: Ensure you pushed the build artifacts to the deploy branch:
|
|
```bash
|
|
git checkout deploy
|
|
ls -la build/ # Should exist
|
|
git log --oneline -1 # Verify latest commit
|
|
```
|
|
|
|
### Caddy Not Serving New Content
|
|
|
|
**Solution**:
|
|
```bash
|
|
# SSH to server
|
|
ssh root@arch-vps
|
|
|
|
# Check Caddy status
|
|
systemctl status caddy
|
|
|
|
# Reload Caddy manually
|
|
systemctl reload caddy
|
|
|
|
# Check logs
|
|
journalctl -u caddy -f
|
|
```
|
|
|
|
### Permission Issues
|
|
|
|
**Solution**:
|
|
```bash
|
|
# SSH to server
|
|
ssh root@arch-vps
|
|
|
|
# Fix ownership
|
|
chown -R caddy:caddy /var/www/jnss-web
|
|
|
|
# Verify
|
|
ls -la /var/www/jnss-web
|
|
```
|
|
|
|
### Git Clone Fails
|
|
|
|
**Error**: Unable to clone from git.jnss.me
|
|
|
|
**Solution**:
|
|
- Verify repository is public in Gitea
|
|
- Test clone manually: `git clone https://git.jnss.me/joakim/jnss-web.git /tmp/test`
|
|
- Check Gitea service status
|
|
|
|
## Rollback Procedure
|
|
|
|
### Option 1: Rollback Deploy Branch
|
|
|
|
```bash
|
|
# In jnss-web repository
|
|
git checkout deploy
|
|
|
|
# Find previous commit
|
|
git log --oneline
|
|
|
|
# Reset to previous commit
|
|
git reset --hard <commit-hash>
|
|
|
|
# Force push
|
|
git push -f origin deploy
|
|
|
|
# Re-run deployment
|
|
cd ~/rick-infra
|
|
ansible-playbook -i inventory/hosts.yml playbooks/deploy-jnss-web.yml
|
|
```
|
|
|
|
### Option 2: Quick Server-Side Rollback
|
|
|
|
```bash
|
|
# SSH to server
|
|
ssh root@arch-vps
|
|
|
|
# Go to repo directory
|
|
cd /opt/jnss-web-repo
|
|
|
|
# Reset to previous commit
|
|
git reset --hard HEAD~1
|
|
|
|
# Re-sync
|
|
rsync -av --delete build/ /var/www/jnss-web/
|
|
|
|
# Reload Caddy
|
|
systemctl reload caddy
|
|
```
|
|
|
|
## Security Considerations
|
|
|
|
- Repository is public (contains only build artifacts)
|
|
- No secrets in build output
|
|
- Caddy serves only /var/www/jnss-web (no parent directory access)
|
|
- Security headers configured in Caddy
|
|
- HTTPS enforced via Caddy with Let's Encrypt
|
|
|
|
## Performance Optimizations
|
|
|
|
- Static assets cached for 1 year (immutable)
|
|
- HTML cached for 1 hour with revalidation
|
|
- Gzip compression enabled
|
|
- No server-side processing required
|
|
|
|
## Monitoring
|
|
|
|
### Check Deployment Status
|
|
|
|
```bash
|
|
# From control machine
|
|
ansible homelab -i inventory/hosts.yml -m shell -a "ls -lh /var/www/jnss-web"
|
|
```
|
|
|
|
### View Access Logs
|
|
|
|
```bash
|
|
ssh root@arch-vps 'tail -100 /var/log/caddy/jnss-web.log | jq .'
|
|
```
|
|
|
|
### Check Site Health
|
|
|
|
```bash
|
|
curl -I https://jnss.me
|
|
curl -I https://www.jnss.me # Should redirect to jnss.me
|
|
```
|
|
|
|
## Files Created
|
|
|
|
This deployment adds the following files to rick-infra:
|
|
|
|
- `playbooks/deploy-jnss-web.yml` - Main deployment playbook
|
|
- `playbooks/templates/jnss-web.caddy.j2` - Caddy configuration template
|
|
- `docs/jnss-web-deployment.md` - This documentation
|
|
|
|
And modifies:
|
|
|
|
- `roles/caddy/templates/Caddyfile.j2` - Removed default site section
|