WP-Ops/README.md

WordOps Dev Project - Server Info

Requirements

Server

• Up-to-date Linux OS (built and tested on Ubuntu 24.04)
• WordOps installed and working (/usr/local/bin/wo)
• WP-CLI 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):

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

   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

   # 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

   # 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.

# 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

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:

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