docs: add INSTALL.md with local, server (systemd), env, ops, troubleshooting

INSTALL.md

@@ -0,0 +1,86 @@
+## 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
+```
+
+