diff --git a/INSTALL.md b/INSTALL.md index 5519384..973e358 100644 --- a/INSTALL.md +++ b/INSTALL.md @@ -1,77 +1,47 @@ -## Install and Operations Guide +## Production Install (Ubuntu + systemd) -This document describes how to install, configure, run, and operate Project Ploughshares locally and on an Ubuntu server. +This file covers production installation only. For all other docs, see README.md. -### 1) Prerequisites -- Docker and Docker Compose plugin installed -- Git installed -- Ubuntu server (for systemd install) with sudo/root access +### Prerequisites +- Ubuntu server with sudo/root access +- Docker and Docker Compose plugin already installed -### 2) Environment Configuration -1. Copy the example env file and set secrets/values: +### Configure environment +1. Copy example env and set required values: - `cp .env.example .env` - - Edit `.env` and set `GOOGLE_API_KEY` and any optional overrides (APP_ENV, DB vars, etc.) + - Edit `.env` and set at least: `GOOGLE_API_KEY` -### 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: +### Install +1. Copy or clone the repo onto the server +2. Run the installer: - `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): +What the installer does: +- Syncs the repo to `/opt/ploughshares` +- Ensures `/opt/ploughshares/.env` exists +- Installs and enables: + - `ploughshares-compose.service` + - `ploughshares-daily-restart.timer` (03:15 daily) +- Starts the stack + +### Change daily restart time ```bash sudo systemctl edit ploughshares-daily-restart.timer -# In the [Timer] section set: OnCalendar=*-*-* HH:MM:SS +# In [Timer] set: OnCalendar=*-*-* HH:MM:SS sudo systemctl daemon-reload sudo systemctl restart ploughshares-daily-restart.timer ``` -### 5) Operations -- Check status: +### Manage +- Status: - `systemctl status ploughshares-compose.service` - `systemctl status ploughshares-daily-restart.timer` -- Start/Stop/Restart stack: +- Start/Stop/Restart: - `sudo systemctl start|stop|restart ploughshares-compose.service` - Logs: - - App containers: `docker logs ` - - Daily restart logs: `/var/log/ploughshares-restart.log` - - Manual restart with logging: `./restart_containers.sh` + - Daily restart: `/var/log/ploughshares-restart.log` -### 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 +### Uninstall ```bash sudo systemctl disable --now ploughshares-daily-restart.timer sudo systemctl disable --now ploughshares-compose.service @@ -79,7 +49,6 @@ 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 ```