diff --git a/dev-panel.vincentdevelopment.ca/htdocs/README.md b/dev-panel.vincentdevelopment.ca/htdocs/README.md index 8b069b2..8b01c30 100644 --- a/dev-panel.vincentdevelopment.ca/htdocs/README.md +++ b/dev-panel.vincentdevelopment.ca/htdocs/README.md @@ -4,7 +4,7 @@ A lightweight internal control panel for managing WordOps WordPress sites withou ## What this does -- Lists WordOps sites (hides `dev-panel.local`) +- Lists WordOps sites (hides the `dev-panel` site itself) - Create / delete sites via WordOps - Optional bootstrap step after site creation (`wp-dev-bootstrap.sh`) - User auth + roles: @@ -18,22 +18,11 @@ A lightweight internal control panel for managing WordOps WordPress sites withou ### 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) - -### 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. +- WordOps installed and working (`/usr/local/bin/wo`) +- WP-CLI installed and working (`wp` in PATH) +- Nginx + PHP-FPM (Provided by WordOps) +- SQLite support for PHP +- Sudo privileges for `www-data` to run WordOps commands without password ### File layout @@ -63,44 +52,15 @@ Helper scripts live at: - `includes/db.php` → `/var/www//htdocs/includes/db.php` - `includes/functions.php` → `/var/www//htdocs/includes/functions.php` - `style.css` → `/var/www//htdocs/style.css` - + Make sure the web server can write the SQLite DB (the panel will create it on first load): `sudo chown -R www-data:www-data /var/www//htdocs` > Optional: lock down later once seeded -3. Install bootstrap + helper scripts - - Copy: - - `wp-dev-bootstrap.sh` → `/usr/local/bin/wp-dev-bootstrap.sh` (custom bootstrap script) - - `wo-fix-perms.sh` → `/usr/local/bin/wo-fix-perms.sh` (optional) - - Then: - - `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 - - Create sudoers file: `sudo visudo -f /etc/sudoers.d/dev-panel` - - Contents: - ```text - 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` - - ## First login / seeding -On first load, if there are no users, the panel auto-creates: +On first load, if there are no users, the panel auto-creates an admin user with the following credentials: ```text Username: admin @@ -109,74 +69,6 @@ Password: change-me Log in and change it immediately using the user dropdown → “Change password”. -### Ownership & permissions strategy - -You have 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 -sudo usermod -aG webdev -... - -# 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` - -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//.ssh/` depending on your model - -**Ensure correct perms:** - -- `/var/www/.ssh` or `/home//.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.** - - ## Daily workflow **Option A:** (recommended) [VSCode Remote - SSH](https://code.visualstudio.com/docs/remote/ssh) @@ -193,7 +85,6 @@ Ensure `known_hosts` contains github.com to avoid prompts: - Map network drives on dev machines - Requires tooling (`node`, `php`, etc) on user machines for composer, Tailwind, etc - ## Troubleshooting ### “PDOException: could not find driver” @@ -217,42 +108,12 @@ Don’t run wo as www-data directly: `sudo -u www-data /usr/local/bin/wo site list` -### WordOps delete prompts / EOFError - -Use `--no-prompt` on deletes (panel already does). - ### Panel isn’t streaming output Bootstrap output streams (proc_open + flush) WordOps sometimes buffers; that’s normal. The panel will still show output when it arrives. - -## Security notes - -The panel’s `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-panel.local/htdocs/panel.sqlite` - - ## Next steps / nice-to-haves - “Fix perms” button in the panel post-create