6ec54460f8
- Create docs/AGENTS.md for AI assistants context - Create docs/WORKFLOWS.md consolidating deployment workflows - Remove redundant docs/root/ folder - Remove .agent/ folder (consolidated into docs/) - Update dates in all documentation files - Simplify README.md documentation section
215 lines
4.5 KiB
Markdown
215 lines
4.5 KiB
Markdown
# Workflows - GoHorse Jobs
|
|
|
|
> **Last Updated:** 2026-02-16
|
|
> **Purpose:** Deployment and operational workflows
|
|
|
|
---
|
|
|
|
## Git Sync (GitHub -> Forgejo)
|
|
|
|
Push changes to both GitHub (origin) and Forgejo (pipe) remotes.
|
|
|
|
### Flow
|
|
|
|
```mermaid
|
|
graph LR
|
|
A[Local] -->|git push| B[GitHub origin]
|
|
B -->|git pull| C[VPS]
|
|
C -->|git push pipe| D[Forgejo pipe]
|
|
```
|
|
|
|
### Commands
|
|
|
|
```bash
|
|
# 1. Push to GitHub (origin)
|
|
git push origin HEAD
|
|
|
|
# 2. Push to Forgejo (pipe)
|
|
git push pipe HEAD
|
|
```
|
|
|
|
### Full Sync (from VPS)
|
|
|
|
```bash
|
|
# 1. Pull from GitHub
|
|
cd /root/gohorsejobs
|
|
git pull origin dev
|
|
|
|
# 2. Push to Forgejo
|
|
git push pipe dev
|
|
|
|
# 3. Sync other branches (optional)
|
|
git pull origin main && git push pipe main
|
|
git pull origin hml && git push pipe hml
|
|
```
|
|
|
|
---
|
|
|
|
## Deploy Frontend
|
|
|
|
Deploy Frontend to Apolo server (dev.gohorsejobs.com).
|
|
|
|
### Prerequisites
|
|
|
|
- Podman installed locally
|
|
- Access to Forgejo registry
|
|
- SSH access to Apolo server
|
|
|
|
### Steps
|
|
|
|
```bash
|
|
# 1. Login to Forgejo Registry
|
|
podman login -u 'y@rede5.com.br' forgejo-gru.rede5.com.br
|
|
|
|
# 2. Build with Production URLs
|
|
cd /home/yamamoto/lab/gohorsejobs
|
|
podman build \
|
|
--build-arg NEXT_PUBLIC_API_URL=https://api-tmp.gohorsejobs.com \
|
|
--build-arg NEXT_PUBLIC_BACKOFFICE_URL=https://b-tmp.gohorsejobs.com \
|
|
-t forgejo-gru.rede5.com.br/rede5/gohorsejobs-frontend:latest \
|
|
-f frontend/Dockerfile frontend/
|
|
|
|
# 3. Push to Registry
|
|
podman push forgejo-gru.rede5.com.br/rede5/gohorsejobs-frontend:latest
|
|
|
|
# 4. Deploy on Apolo
|
|
ssh root@apolo 'podman pull forgejo-gru.rede5.com.br/rede5/gohorsejobs-frontend:latest && systemctl restart gohorsejobs-frontend-dev'
|
|
|
|
# 5. Verify
|
|
ssh root@apolo 'systemctl status gohorsejobs-frontend-dev --no-pager | tail -5'
|
|
```
|
|
|
|
### Environment Reference
|
|
|
|
| Variable | Production Value |
|
|
|----------|------------------|
|
|
| `NEXT_PUBLIC_API_URL` | `https://api-tmp.gohorsejobs.com` |
|
|
| `NEXT_PUBLIC_BACKOFFICE_URL` | `https://b-tmp.gohorsejobs.com` |
|
|
| `NEXT_PUBLIC_SEEDER_API_URL` | `https://seeder.gohorsejobs.com` |
|
|
|
|
---
|
|
|
|
## Deploy Backend
|
|
|
|
Deploy Backend API to Apolo server (api-tmp.gohorsejobs.com).
|
|
|
|
### Steps
|
|
|
|
```bash
|
|
# 1. Login to Forgejo Registry
|
|
podman login forgejo-gru.rede5.com.br
|
|
|
|
# 2. Build
|
|
cd backend
|
|
podman build -t forgejo-gru.rede5.com.br/rede5/gohorsejobs-backend:latest .
|
|
|
|
# 3. Push
|
|
podman push forgejo-gru.rede5.com.br/rede5/gohorsejobs-backend:latest
|
|
|
|
# 4. Deploy on Apolo
|
|
ssh root@apolo 'podman pull forgejo-gru.rede5.com.br/rede5/gohorsejobs-backend:latest && systemctl restart gohorsejobs-backend-dev'
|
|
```
|
|
|
|
---
|
|
|
|
## Deploy Backoffice
|
|
|
|
Deploy Backoffice API to Apolo server (b-tmp.gohorsejobs.com).
|
|
|
|
### Steps
|
|
|
|
```bash
|
|
# 1. Build
|
|
cd backoffice
|
|
podman build -t forgejo-gru.rede5.com.br/rede5/gohorsejobs-backoffice:latest .
|
|
|
|
# 2. Push
|
|
podman push forgejo-gru.rede5.com.br/rede5/gohorsejobs-backoffice:latest
|
|
|
|
# 3. Deploy
|
|
ssh root@apolo 'podman pull forgejo-gru.rede5.com.br/rede5/gohorsejobs-backoffice:latest && systemctl restart gohorsejobs-backoffice-dev'
|
|
```
|
|
|
|
---
|
|
|
|
## Database Operations
|
|
|
|
### Run Migrations
|
|
|
|
```bash
|
|
# Local
|
|
cd backend && go run ./cmd/manual_migrate
|
|
|
|
# Via SSH (remote)
|
|
ssh root@apolo 'cd /mnt/data/gohorsejobs/backend && ./migrate.sh'
|
|
```
|
|
|
|
### Seed Database
|
|
|
|
```bash
|
|
# Trigger Seeder API
|
|
curl -X POST https://seeder.gohorsejobs.com/seed
|
|
|
|
# Local
|
|
cd seeder-api && npm run seed
|
|
```
|
|
|
|
### Database Shell
|
|
|
|
```bash
|
|
# Via SSH
|
|
ssh root@apolo 'podman exec -it postgres-main psql -U yuki -d gohorsejobs_dev'
|
|
```
|
|
|
|
---
|
|
|
|
## Service Management (Apolo)
|
|
|
|
### View Status
|
|
|
|
```bash
|
|
ssh root@apolo 'systemctl status gohorsejobs-backend-dev --no-pager'
|
|
ssh root@apolo 'systemctl status gohorsejobs-frontend-dev --no-pager'
|
|
ssh root@apolo 'systemctl status gohorsejobs-backoffice-dev --no-pager'
|
|
ssh root@apolo 'systemctl status gohorsejobs-seeder-dev --no-pager'
|
|
```
|
|
|
|
### Restart Services
|
|
|
|
```bash
|
|
# All services
|
|
ssh root@apolo 'systemctl restart gohorsejobs-backend-dev gohorsejobs-frontend-dev gohorsejobs-backoffice-dev gohorsejobs-seeder-dev'
|
|
|
|
# Individual service
|
|
ssh root@apolo 'systemctl restart gohorsejobs-backend-dev'
|
|
```
|
|
|
|
### View Logs
|
|
|
|
```bash
|
|
ssh root@apolo 'journalctl -u gohorsejobs-backend-dev -f --no-pager'
|
|
```
|
|
|
|
---
|
|
|
|
## Troubleshooting
|
|
|
|
### CI/CD Workflow Not Starting
|
|
|
|
**Symptom**: "Waiting for runner..."
|
|
|
|
**Solution**:
|
|
1. Check `.forgejo/workflows/deploy.yaml` for `runs-on` label
|
|
2. Verify runner has matching label in config
|
|
|
|
### SSH Connection Failed
|
|
|
|
**Solution**:
|
|
1. Verify public key is in `~/.ssh/authorized_keys`
|
|
2. Check IP accessibility from runner network
|
|
|
|
### Build Failed in Podman
|
|
|
|
**Solution**:
|
|
1. Run `podman logs -f <container>` for details
|
|
2. Verify user has podman permissions (rootless or sudo)
|