/home/techb158/trellopowerup.abdallabala.com/docs
Edit: /home/techb158/trellopowerup.abdallabala.com/docs/32-vps-deployment-guide.md (3697B)
# VPS Deployment Guide for Trello Power-Up
This guide deploys the COSMIC AI-Risk Trello Power-Up to a VPS with Docker Compose and an HTTPS reverse proxy.
## Requirements
- VPS with Ubuntu/Debian or similar Linux.
- A domain or subdomain pointed to the VPS, for example `trello.yourdomain.com`.
- Docker and Docker Compose installed.
- Nginx or another reverse proxy with HTTPS.
- Trello Power-Up API key.
Trello requires the connector URL and iframe pages to load over HTTPS.
## Files Added for VPS
- `docker-compose.vps.yml` - VPS-friendly Compose file.
- `.dockerignore` - keeps `node_modules`, `.env`, `data`, and logs out of the Docker build context.
## Local Upload Option
From your local project folder, create an archive that excludes runtime files:
```bash
tar --exclude=node_modules --exclude=data --exclude=.env --exclude=.git -czf cosmic-trello-powerup.tar.gz .
```
Upload it to the VPS:
```bash
scp cosmic-trello-powerup.tar.gz USER@SERVER_IP:/opt/
```
On the VPS:
```bash
sudo mkdir -p /opt/cosmic-trello-powerup
sudo tar -xzf /opt/cosmic-trello-powerup.tar.gz -C /opt/cosmic-trello-powerup
cd /opt/cosmic-trello-powerup
```
## VPS Environment File
Create `/opt/cosmic-trello-powerup/.env`:
```env
PORT=3000
HOST_PORT=3000
PUBLIC_BASE_URL=https://trello.yourdomain.com
TRELLO_API_KEY=replace_with_power_up_api_key
TRELLO_APP_NAME=COSMIC AI-Risk Management
ALLOWED_ORIGINS=https://trello.com,https://*.trello.com,https://trello.yourdomain.com
COSMIC_STORE_FILE=./data/store.json
COSMIC_REVIEW_STALE_DAYS=30
```
Create runtime storage:
```bash
mkdir -p data
```
## Build and Start
```bash
docker compose -f docker-compose.vps.yml up -d --build
```
Check status:
```bash
docker compose -f docker-compose.vps.yml ps
docker compose -f docker-compose.vps.yml logs -f
```
Health check from the VPS:
```bash
curl http://127.0.0.1:3000/api/health
```
Expected version is currently `0.4.5`.
## Nginx Reverse Proxy Example
Create `/etc/nginx/sites-available/trello-powerup`:
```nginx
server {
listen 80;
server_name trello.yourdomain.com;
location / {
proxy_pass http://127.0.0.1:3000;
proxy_http_version 1.1;
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;
}
}
```
Enable it:
```bash
sudo ln -s /etc/nginx/sites-available/trello-powerup /etc/nginx/sites-enabled/trello-powerup
sudo nginx -t
sudo systemctl reload nginx
```
Add HTTPS with Certbot:
```bash
sudo certbot --nginx -d trello.yourdomain.com
```
After HTTPS is active, verify:
```bash
curl https://trello.yourdomain.com/api/health
```
## Trello Power-Up Admin
In Trello Power-Up admin, set connector URL to:
```text
https://trello.yourdomain.com/index.html
```
Enable these capabilities:
- `authorization-status`
- `show-authorization`
- `show-settings`
- `board-buttons`
- `card-buttons`
- `card-badges`
- `card-detail-badges`
- `card-back-section`
Then add the Power-Up to a Trello board and set the COSMIC API base URL to:
```text
https://trello.yourdomain.com
```
## Update Deployment Later
Upload the new archive, then on the VPS:
```bash
cd /opt/cosmic-trello-powerup
docker compose -f docker-compose.vps.yml up -d --build
```
The `./data` folder is mounted into the container, so local JSON runtime data survives rebuilds.
## Notes
- JSON storage is acceptable for prototype VPS testing.
- For production multi-user usage, replace JSON storage with PostgreSQL or another managed database.
- Do not commit `.env` or upload local `data` unless you intentionally want to migrate runtime data.