## Install and Operations Guide

This document describes how to install, configure, run, and operate Project Ploughshares locally and on an Ubuntu server.

### 1) Prerequisites
- Docker and Docker Compose plugin installed
- Git installed
- Ubuntu server (for systemd install) with sudo/root access

### 2) Environment Configuration
1. Copy the example env file and set secrets/values:
   - `cp .env.example .env`
   - Edit `.env` and set `GOOGLE_API_KEY` and any optional overrides (APP_ENV, DB vars, etc.)

### 3) Local Development
- Start the dev stack:
  - `docker-compose -f docker-compose.dev.yml up --build`
- Access the app:
  - `http://localhost:5005`
- Run crawlers (provide GOOGLE_API_KEY in `.env`):
  - Google Alerts: `docker-compose -f docker-compose.dev.yml run --rm crawler_google_alerts`
  - Marketline: `docker-compose -f docker-compose.dev.yml run --rm crawler_marketline`

### 4) Server Install (Ubuntu + systemd)
The repo includes a non-interactive installer that deploys to `/opt/ploughshares`, installs systemd unit/timer, and starts services.

Steps:
1. Ensure Docker + Compose are installed on the server
2. Copy the repo to the server (or clone) and run:
   - `sudo ./install.sh`
3. The installer will:
   - Sync repo to `/opt/ploughshares`
   - Ensure `/opt/ploughshares/.env` exists (from example if absent)
   - Install `ploughshares-compose.service` and `ploughshares-daily-restart.timer`
   - Enable and start both

Change daily restart time (default 03:15):
```bash
sudo systemctl edit ploughshares-daily-restart.timer
# In the [Timer] section set: OnCalendar=*-*-* HH:MM:SS
sudo systemctl daemon-reload
sudo systemctl restart ploughshares-daily-restart.timer
```

### 5) Operations
- Check status:
  - `systemctl status ploughshares-compose.service`
  - `systemctl status ploughshares-daily-restart.timer`
- Start/Stop/Restart stack:
  - `sudo systemctl start|stop|restart ploughshares-compose.service`
- Logs:
  - App containers: `docker logs <container_name>`
  - Daily restart logs: `/var/log/ploughshares-restart.log`
  - Manual restart with logging: `./restart_containers.sh`

### 6) Cron alternative (optional)
If you prefer cron instead of systemd timer, use the helper:
- `INTERVAL="15 3 * * *" ./install_daily_restart_cron.sh`

### 7) CI/CD
- Woodpecker builds the app and crawler images per `.woodpecker.yml`

### 8) Troubleshooting
- Containers not starting:
  - `docker-compose -f docker-compose.yml up -d` (server) or `docker-compose -f docker-compose.dev.yml up -d` (local)
  - `docker compose ps` / `docker compose logs -f app`
- Missing GOOGLE_API_KEY:
  - Set in `.env` and re-run
- Systemd unit not found:
  - `sudo systemctl daemon-reload`
- Permission issues writing logs:
  - Ensure `/var/log` is writable by root; logs written by systemd service

### 9) Uninstall
```bash
sudo systemctl disable --now ploughshares-daily-restart.timer
sudo systemctl disable --now ploughshares-compose.service
sudo rm -f /etc/systemd/system/ploughshares-daily-restart.timer
sudo rm -f /etc/systemd/system/ploughshares-daily-restart.service
sudo rm -f /etc/systemd/system/ploughshares-compose.service
sudo systemctl daemon-reload
# Preserve data if needed:
sudo rm -rf /opt/ploughshares
```