From 2722cfb81e7cf08eb0b11528c0336603977fe4c0 Mon Sep 17 00:00:00 2001
From: dev <dev@vincentdesign.ca>
Date: Thu, 1 Jan 2026 20:32:25 +0000
Subject: [PATCH] =?UTF-8?q?=F0=9F=93=84=20docs:=20Add=20main=20project=20r?=
 =?UTF-8?q?eadme?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 README.md | 190 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 190 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..e90d2f8
--- /dev/null
+++ b/README.md
@@ -0,0 +1,190 @@
+# WordOps Dev Project - Server Info
+
+## Requirements
+
+### Server
+
+- Up-to-date Linux OS (built and tested on Ubuntu 24.04)
+- [WordOps](https://wordops.net/) installed and working (`/usr/local/bin/wo`)
+- [WP-CLI](https://wp-cli.org/) installed and working (`wp` in PATH)
+- Nginx + PHP-FPM (WordOps provides this)
+- SQLite support for PHP
+- Sudo privileges for `www-data` to run WordOps commands without password
+
+### PHP packages
+
+Install SQLite support for PHP (required):
+
+```bash
+sudo apt update
+sudo apt install -y php-sqlite3
+sudo systemctl restart php8.3-fpm || true
+sudo systemctl restart php-fpm || true
+```
+> Adjust `php8.3-fpm` to your PHP version (if needed).
+
+## Install steps
+
+1. Install WordOps
+
+    `wget -qO wo wops.cc && sudo bash wo`
+
+2. Install WP-CLI
+
+    ```bash
+    curl -O https://raw.githubusercontent.com/wp-cli/builds/gh-pages/phar/wp-cli.phar
+
+    # check the Phar file to verify that it’s working
+    php wp-cli.phar --info
+
+    # make the file executable and move it to /usr/local/bin
+    chmod +x wp-cli.phar
+    sudo mv wp-cli.phar /usr/local/bin/wp
+
+    # verify installation
+    wp --info
+    ```
+
+3. Install bootstrap + helper scripts
+
+    ```bash
+    # install helpers
+    cp helpers/wp-dev-bootstrap.sh /usr/local/bin/wp-dev-bootstrap.sh
+    cp helpers/wo-fix-perms.sh /usr/local/bin/wo-fix-perms.sh
+
+    # make helpers executable
+    sudo chmod +x /usr/local/bin/wp-dev-bootstrap.sh
+    sudo chmod +x /usr/local/bin/wo-fix-perms.sh
+    ```
+
+4. Allow www-data to run WordOps + scripts via sudo
+
+    ```bash
+    # create sudoers file
+    sudo visudo -f /etc/sudoers.d/dev-panel
+
+    # contents
+    www-data ALL=(root) NOPASSWD: /usr/local/bin/wo *
+    www-data ALL=(root) NOPASSWD: /usr/local/bin/wp-dev-bootstrap.sh *
+    www-data ALL=(root) NOPASSWD: /usr/local/bin/wo-fix-perms.sh *
+    ```
+
+      This lets the panel (running as www-data) execute the exact commands it needs as root.
+
+      > **Do not add `www-data` to the sudo group.**
+
+      Test:
+      `sudo -u www-data sudo /usr/local/bin/wo site list`
+
+## Ownership & permissions strategy
+
+There are two competing needs:
+
+1. WordPress / PHP needs to write certain files
+2. Developers need to edit themes/plugins without being root
+
+A safe, simple model is group-based permissions.
+
+```bash
+# Create a shared dev group
+sudo groupadd webdev || true
+
+# Add all devs to group
+sudo usermod -aG webdev <devUser1>
+sudo usermod -aG webdev <devUser2>
+...
+
+# Add web server user
+sudo usermod -aG webdev www-data
+```
+
+Log out and back in for group membership to apply.
+
+### Set group ownership + setgid under `/var/www`
+
+```bash
+sudo chown -R root:webdev /var/www
+
+# Directories: 2775 (setgid + group writable)
+sudo find /var/www -type d -exec chmod 2775 {} \;
+
+# Files: 664 (group writable)
+sudo find /var/www -type f -exec chmod 664 {} \;
+```
+
+### Ensure new files stay group-writable
+
+Make sure your bootstrap script starts with `umask 0002` (the includd helper already does this).
+
+If WordOps creates files with different perms, run the optional fixer after site creation:
+
+`sudo /usr/local/bin/wo-fix-perms.sh example.local`
+
+### SSH keys for private repos (bootstrap theme cloning)
+
+If your bootstrap clones private repos, you’ll need a key that can access them.
+
+**Option A** (recommended): deploy key or bot account key for the server
+
+Create `/var/www/.ssh/` or `/home/<serviceUser>/.ssh/` depending on your model
+
+**Ensure correct perms:**
+
+- `/var/www/.ssh` or `/home/<serviceUser>/.ssh` = 700
+- private key = 600
+
+Add to GitHub as a deploy key or bot account key
+
+Ensure `known_hosts` contains github.com to avoid prompts:
+
+`sudo -u www-data ssh-keyscan github.com >> /var/www/.ssh/known_hosts`
+
+**Option B:** keep bootstrap theme cloning optional and run theme cloning from a dev account via VSCode Remote.
+
+**Don’t store a personal private key in a shared server environment.**
+
+## Troubleshooting
+
+### “PDOException: could not find driver”
+
+PHP SQLite extension missing:
+
+```bash
+sudo apt install -y php-sqlite3
+sudo systemctl restart php8.3-fpm
+```
+
+### WordOps fails when run as www-data
+
+Don’t run wo as www-data directly:
+
+**Correct** (what the panel does):
+
+`sudo -u www-data sudo /usr/local/bin/wo site list`
+
+**Incorrect**:
+
+`sudo -u www-data /usr/local/bin/wo site list`
+
+## Security notes
+
+The `sudoers` file is the main security boundary:
+
+- Keep it as narrow as possible
+- Avoid wildcarding unrelated commands
+- Consider restricting panel access by:
+  - Internal network only
+  - VPN only
+  - HTTP basic auth in front of it
+- Keep OS patches current
+- Regularly audit panel users + roles
+
+## Backups (minimum viable)
+
+At minimum, back up:
+
+- /var/www (all site roots)
+- Databases (WordOps MariaDB/MySQL)
+- `/etc/nginx` and WordOps configs (optional but helpful)
+- Panel SQLite DB:
+  - `/var/www/<dev panelURL>/htdocs/panel.sqlite`