colin
/
ploughshares
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
ploughshares/INSTALL.md

3.2 KiB
Raw Blame History

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):

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

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