Add README with install, development, production, and migration instructions

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-07-13 08:14:21 -04:00
parent 6bbe045ea6
commit f9283de190
1 changed files with 125 additions and 0 deletions
@@ -0,0 +1,125 @@
+# Bible Study App
+
+A self-hosted Bible study tool with notes, projects, and user accounts.
+
+---
+
+## Requirements
+
+- **Node.js v18 or higher** — [nodejs.org](https://nodejs.org/)
+- **npm** (bundled with Node.js)
+- **GCC / make** (only needed for production/server installs — required to build the `better-sqlite3` native module)
+
+---
+
+## Quick Start (Development)
+
+```bash
+git clone https://github.com/nmemmert/study-bible-project.git
+cd study-bible-project
+bash setup.sh
+```
+
+`setup.sh` installs dependencies, finds a free port, and starts both servers:
+
+| Server | Default URL |
+|--------|-------------|
+| API (Express) | http://localhost:3001 |
+| Frontend (Vite) | http://localhost:5173 |
+
+**Stop the servers:**
+```bash
+kill $(cat .api.pid) $(cat .vite.pid)
+```
+
+**View logs:**
+```bash
+tail -f .api.log    # API server
+tail -f .vite.log   # Vite dev server
+```
+
+---
+
+## Production Install (Rocky Linux / systemd)
+
+Installs the app as a persistent systemd service under `/opt/study-app`.
+
+```bash
+git clone https://github.com/nmemmert/study-bible-project.git
+cd study-bible-project
+
+# Install build tools (first time only)
+sudo dnf groupinstall -y "Development Tools"
+sudo dnf install -y python3
+
+# Install and enable the service
+sudo bash deploy/install.sh
+```
+
+The installer will:
+1. Install Node.js dependencies and build the frontend
+2. Create a `study-app` system user
+3. Register and start a systemd service
+
+**Useful commands after install:**
+```bash
+systemctl status study-app          # Check service status
+journalctl -u study-app -f          # Stream logs
+systemctl restart study-app         # Restart after an update
+```
+
+**Open the firewall port (if needed):**
+```bash
+sudo firewall-cmd --add-port=3001/tcp --permanent
+sudo firewall-cmd --reload
+```
+
+The app listens on **port 3001** by default. Set the `PORT` environment variable in the systemd unit to change it.
+
+---
+
+## Updating (Production)
+
+```bash
+cd /path/to/study-bible-project
+git pull
+sudo bash deploy/install.sh
+```
+
+The installer preserves the session secret across updates so logged-in users are not signed out.
+
+---
+
+## Migrating to a New Machine
+
+**On the old machine — create a backup:**
+```bash
+npm run backup
+```
+This creates `study-app-backup_<timestamp>.zip` in the project root.
+
+**On the new machine — restore after cloning and installing:**
+```bash
+npm run restore study-app-backup_<timestamp>.zip
+```
+
+See [scripts/backup-data.sh](scripts/backup-data.sh) and [scripts/restore-data.sh](scripts/restore-data.sh) for details.
+
+---
+
+## Project Structure
+
+```
+├── server/          # Express API + SQLite database
+│   └── data/        # projects.db lives here (gitignored)
+├── src/             # React frontend (Vite)
+├── deploy/          # systemd service unit + install script
+├── scripts/         # backup / restore helpers
+└── setup.sh         # Development quick-start
+```
+
+---
+
+## License
+
+Private / personal use.