Add deployment guide to WEB_UI.md
Includes: - Quick start instructions - Environment variables - Database configuration (with mergerfs note) - systemd service example - nginx reverse proxy config - SSL setup with certbot - Tailwind CSS build commands - Health check and troubleshooting 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
parent
b26ae5092b
commit
24c91b8de7
147
docs/WEB_UI.md
147
docs/WEB_UI.md
|
|
@ -1303,6 +1303,153 @@ The web UI consumes these existing API endpoints:
|
|||
- Web UI strategy: `discussions/diagrams/smarttools-web-ui-strategy.puml`
|
||||
- UI visual strategy: `discussions/diagrams/smarttools-web-ui-visual-strategy.puml`
|
||||
|
||||
## Deployment Guide
|
||||
|
||||
### Requirements
|
||||
|
||||
- Python 3.11+
|
||||
- pip/virtualenv
|
||||
- SQLite 3 (included with Python)
|
||||
|
||||
### Quick Start (Development)
|
||||
|
||||
```bash
|
||||
# Clone the repository
|
||||
git clone https://gitea.brrd.tech/rob/SmartTools.git
|
||||
cd SmartTools
|
||||
|
||||
# Create virtual environment
|
||||
python3 -m venv venv
|
||||
source venv/bin/activate
|
||||
|
||||
# Install with registry extras
|
||||
pip install -e ".[registry]"
|
||||
|
||||
# Run the web server
|
||||
python -m smarttools.web.app
|
||||
```
|
||||
|
||||
The server will start on `http://localhost:5000`.
|
||||
|
||||
### Production Deployment
|
||||
|
||||
#### 1. Environment Variables
|
||||
|
||||
```bash
|
||||
# Required
|
||||
export SMARTTOOLS_REGISTRY_DB=/path/to/registry.db
|
||||
export PORT=5050
|
||||
|
||||
# Optional
|
||||
export SMARTTOOLS_ENV=production # Enables secure cookies
|
||||
export SMARTTOOLS_SHOW_ADS=true # Enable ad placeholders
|
||||
```
|
||||
|
||||
#### 2. Database Location
|
||||
|
||||
By default, the registry uses `~/.smarttools/registry.db`. For production:
|
||||
|
||||
```bash
|
||||
# Create dedicated directory
|
||||
mkdir -p /var/lib/smarttools
|
||||
export SMARTTOOLS_REGISTRY_DB=/var/lib/smarttools/registry.db
|
||||
```
|
||||
|
||||
**Note**: If using a merged filesystem (e.g., mergerfs), store the database on a single disk or in `/tmp` to avoid SQLite WAL mode issues:
|
||||
|
||||
```bash
|
||||
export SMARTTOOLS_REGISTRY_DB=/tmp/smarttools-registry/registry.db
|
||||
```
|
||||
|
||||
#### 3. Running with systemd
|
||||
|
||||
Create `/etc/systemd/system/smarttools-registry.service`:
|
||||
|
||||
```ini
|
||||
[Unit]
|
||||
Description=SmartTools Registry Web Server
|
||||
After=network.target
|
||||
|
||||
[Service]
|
||||
Type=simple
|
||||
User=smarttools
|
||||
WorkingDirectory=/opt/smarttools
|
||||
Environment=SMARTTOOLS_REGISTRY_DB=/var/lib/smarttools/registry.db
|
||||
Environment=PORT=5050
|
||||
Environment=SMARTTOOLS_ENV=production
|
||||
ExecStart=/opt/smarttools/venv/bin/python -m smarttools.web.app
|
||||
Restart=always
|
||||
RestartSec=5
|
||||
|
||||
[Install]
|
||||
WantedBy=multi-user.target
|
||||
```
|
||||
|
||||
```bash
|
||||
sudo systemctl daemon-reload
|
||||
sudo systemctl enable smarttools-registry
|
||||
sudo systemctl start smarttools-registry
|
||||
```
|
||||
|
||||
#### 4. Reverse Proxy (nginx)
|
||||
|
||||
```nginx
|
||||
server {
|
||||
listen 80;
|
||||
server_name registry.smarttools.dev;
|
||||
|
||||
location / {
|
||||
proxy_pass http://127.0.0.1:5050;
|
||||
proxy_set_header Host $host;
|
||||
proxy_set_header X-Real-IP $remote_addr;
|
||||
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
|
||||
proxy_set_header X-Forwarded-Proto $scheme;
|
||||
}
|
||||
|
||||
location /static {
|
||||
alias /opt/smarttools/src/smarttools/web/static;
|
||||
expires 1y;
|
||||
add_header Cache-Control "public, immutable";
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### 5. SSL with Certbot
|
||||
|
||||
```bash
|
||||
sudo certbot --nginx -d registry.smarttools.dev
|
||||
```
|
||||
|
||||
### Tailwind CSS Build
|
||||
|
||||
The CSS is pre-built and committed. To rebuild after changes:
|
||||
|
||||
```bash
|
||||
# Install dependencies
|
||||
npm install
|
||||
|
||||
# Build for production
|
||||
npx tailwindcss -i src/smarttools/web/static/css/input.css \
|
||||
-o src/smarttools/web/static/css/main.css \
|
||||
--minify
|
||||
```
|
||||
|
||||
### Health Check
|
||||
|
||||
```bash
|
||||
curl http://localhost:5050/api/v1/tools
|
||||
# Returns: {"data":[],"meta":{"page":1,"per_page":20,"total":0,"total_pages":1}}
|
||||
```
|
||||
|
||||
### Troubleshooting
|
||||
|
||||
| Issue | Solution |
|
||||
|-------|----------|
|
||||
| `disk I/O error` | Move database to non-merged filesystem |
|
||||
| Port already in use | Change PORT environment variable |
|
||||
| 500 errors | Check `/tmp/smarttools.log` for stack traces |
|
||||
| Static files not loading | Verify static folder path in deployment |
|
||||
|
||||
## Future Considerations (Phase 8+)
|
||||
|
||||
- **Forum integration**: External (Discourse) or built-in discussions
|
||||
|
|
|
|||
Loading…
Reference in New Issue