Features

• Two WordPress sites: https://www.example1.com and https://www.example2.com.
• Redirects from https://example1.com, http://example1.com, http://www.example1.com to https://example1.com (and the same for example2.com).
• Let’s encrypt certificates.
• WordPress debug logging with logrotate. I have ranted previously about why I think having debug logging turned on is important on live sites.
• Emails must work in WordPress.
• The containers must run as a service, so that they start with system start, and exit gracefully on system shutdown.
• Daily backups of all WordPress files and MySQL databases.
• Networks of the two sites should be isolated for security.

Shameless plug of my referral links

We start with a hosted server. This can be a dedicated server or a server slice. Hosting providers that I like are:

• DigitalOcean – Using this link you get a $200, 60-day credit to try their products. If you spend $25 after your credit expires, I will get $25 in credit.
• Hostinger – You don’t get anything with this link, except for a great hosting service. Again, I get a commission from this link if you stick with Hostinger for 45 days. Think of it as my reward for writing such a great article for you.

I have a Debian droplet on DigitalOcean with 2GB of RAM, but with some tweaking it’s possible to squeeze two low-traffic WordPress sites in 1GB, if you really need to keep the monthly costs down.

First let’s get the (DNS) record straight

The first order of business is to setup the DNS records. We’re going to need two A records to point to our server’s IP, and two CNAME records that will be wwww. aliases of the bare domain. Oh, and we’ll need some NS records to point to the domain name provider (in this case Digital Ocean).

I like to keep the TTL (Time-To-Live) values low until I’m finished with my setup. I’ve set everything to 1800 seconds which is half an hour. Once I’m sure that everything is OK, I can increase the values to something larger like 14400 (four hours).

ssh

We are going to need to be able to login to the server with a passwordless setup.

Login as root to the new server via the admin console.

Create a regular user with adduser:

adduser yourusername

Then add the user to sudoers with:

usermod -aG sudo yourusername

(Replace yourusername with your username.)

Once we are on our local machine, we check if we already have an ssh key with:

ls -al ~/.ssh/id_*.pub

If we don’t have any, we can generate one with:

ssh-keygen -t rsa -b 4096 -C "your_email@domain.com"

Once we are sure that there is a key, we upload it to the new server with:

ssh-copy-id yourusername@server_ip_address

(Again replace yourusername with your remote username, and server_ip_address with your ip address. You will need to enter the password you entered in adduser.)

Docker compose

First, let’s install docker on the server by following the installation instructions for Debian. I am not going to repeat the instructions here. If you have chosen a different distro, follow the respective instructions.

We are going to create a docker-compose.yml file. This file describes how the different docker containers are orchestrated.

We are going to need four containers:

• Two databases for the two sites.
• Two WordPress installations.

I’m first going to show some simple compose configs with the basics, then we are going to add the bells and whistles. Here goes:

Two databases, sitting in a server

version: "3.8"

name: droplet

networks:
    net1:
    net2:

volumes:
  db1volume:
  db2volume:

services:

  db1:
    image: mysql:8.2.0
    networks:
      - net1
    restart: unless-stopped
    expose:
      - "3306"
    volumes:
      - db1volume:/var/lib/mysql
    environment:
      MYSQL_ROOT_PASSWORD: wp1_root_pass
      MYSQL_DATABASE: wp_db1
      MYSQL_USER: db1_user
      MYSQL_PASSWORD: db1_pass

  db2:
    image: mysql:8.2.0
    networks:
      - net2
    restart: unless-stopped
    expose:
      - "3306"
    volumes:
      - db2volume:/var/lib/mysql
    environment:
      MYSQL_ROOT_PASSWORD: wp2_root_pass
      MYSQL_DATABASE: wp_db2
      MYSQL_USER: db2_user
      MYSQL_PASSWORD: db2_pass

There’s already a lot going on here:

• We are defining our composition to have a name. Here I am using droplet. This will also be the prefix for the names of all the containers.
• We are defining two networks, net1 and net2. Only containers on the same network can talk to each other. We don’t want our example1.com WordPress to have any access to the MySQL database of example2.com.
• Next we are defining two identical mysql:8.2.0 containers, named db1 and db2.
• Each of the two databases is put in its respective network (net1 and net2).
• We want a database that has crashed to restart, unless we explicitly stop it.
• We are going to let the databases listen to TCP port 3306. This is the port where WordPress will connect. All other ports are firewalled.
• We are going to mount the /var/lib/mysql directories into docker volumes named db1volume and db2volume.
• Next we are going to use some environment variables that the startup script inside the mysql image recognizes. These will set up a root password, a new empty database, and a username/password pair that WordPress will use to access this new database. The startup script will do all the CREATE DATABASE, CREATE USER and GRANT magic for us. You can learn more about the MySQL docker image here.

A tale of two WordPresses

Next, let’s also add the two WordPress services (these also go under the services section along with the databases):

  wp1:
    image: wordpress:latest
    networks:
      - net1
    depends_on:
      - db1
    user: 1000:1000
    restart: unless-stopped
    expose:
      - "80"
    volumes:
      - ./wp1fs:/var/www/html
    ports:
      - "127.0.0.1:8101:80"
    environment:
      WORDPRESS_DB_HOST: db1:3306
      WORDPRESS_DB_NAME: wp_db1
      WORDPRESS_DB_USER: db1_user
      WORDPRESS_DB_PASSWORD: db1_pass
      WORDPRESS_DEBUG: true

  wp2:
    image: wordpress:latest
    networks:
      - net2
    depends_on:
      - db1
    restart: unless-stopped
    expose:
      - "80"
    volumes:
      - ./wp2fs:/var/www/html
    ports:
      - "127.0.0.1:8102:80"
    environment:
      WORDPRESS_DB_HOST: db2:3306
      WORDPRESS_DB_NAME: wp_db2
      WORDPRESS_DB_USER: db2_user
      WORDPRESS_DB_PASSWORD: db2_pass
      WORDPRESS_DEBUG: true

• We have named the two WordPress containers wp1 and wp2 and assigned them to our two networks, net1 and net2.
• We have defined that these depend on their respective databases to function.
• We have defined that these containers are to be restarted if they crash, but not if we explicitly stop them.
• We are exposing only HTTP port 80 to the networks. All other ports are firewalled. We are not exposing port 443 here. TLS encryption will be done at the host level that will run the reverse proxy (see below).
• We are mounting two local directories here ./wp1fs and ./wp2fs. These will contain the WordPress installations. The first time that the containers run, WordPress will be installed in them. A special wp-config.php file will be placed in there. This file pulls the DB connection settings from the environment variables that we specify below.
• We are port-mapping the HTTP 80 ports to the host’s ports 8101 and 8102. These are the ports that the reverse proxy will use. They are bound to the loopback network (127.0.0.1), and are therefore not exposed to the outside world. If we had used just 8101:80, this would map port 80 of the container to port 8101 of the host on all network interfaces, including the one facing the outside world. This is not ideal. We only want access to our services through our reverse proxy.
• The WORDPRESS_* environment variables are specific to this wordpress image. We specify the databases, the login credentials that we also specified above, and we turn on debug logging. To learn more about these environment variables, click here.

NOTE: I have made the decision here to put the databases into system volumes (these live usually in /var/lib/docker/volumes and can be shared between containers, the WordPress filesystems are mounted in local directories which I call wp1volume and wp2volume. If you prefer to have all volumes unde /var/lib, you can delete the ./ prefix in front of the volume names.

The bells and whistles

If you thought that’s enough, you are gravely mistaken. Here’s a few more things to take care of:

Database collation

We are going to set the databases a UTF-8 multibyte collation for unicode support. Under the environment variables in the database services, we are going to add an explicit mysqld command:

command: "mysqld --character-set-server=utf8mb4 --collation-server=utf8mb4_unicode_ci

And under the WordPress services, we are going to add the following environment variable:

  WORDPRESS_DB_COLLATE: utf8mb4_unicode_ci

File permissions

If we run the above containers, WordPress won’t be able to install or remove any themes or plugins, and it won’t be able to do anything that requires writing to the file system.

This is because, in the WordPress images, the user that runs apache has a different uid and guid than the file system. The files are owned by uid 1000 and guid 1000. We can specify that the user running stuff inside the container has the same numeric ids. To do this, we add the following to the two WordPress services:

user: 1000:1000

Database memory

By default, a mysql instance will take up at least 360MB of memory once it’s running. Most of it is because of the Performance Schema instruments, which take up a lot of memory.

The Performance Schema is a database that keeps track of the mysqld server’s performance, and is useful for diagnostics. If you are not going to use this feature, then you can turn it off. The memory usage of each DB container will then fall to a little over 100MB.

We are going to create a file named disable-perf-schema.cnf with the following contents:

[mysqld]
performance_schema = OFF

This will be added to the mysql server’s config files. The server includes any .cnf files in the /etc/mysql/conf.d directory into its configuration. We can use the volumes section to map this file into our two db containers:

volumes:
  - db1:/var/lib/mysql
  - ./disable-perf-schema.cnf:/etc/mysql/conf.d/disable-perf-schema.cnf

volumes:
  - db2:/var/lib/mysql
  - ./disable-perf-schema.cnf:/etc/mysql/conf.d/disable-perf-schema.cnf

There are more hacks to reduce the memory usage of mysqld, but these are beyond the scope of this article. For example, you can look into reducing the InnoDB buffer pool size.

Log rotate

We have enabled debug logging, because reasons. This is cool, but the /var/www/html/wp-content/debug.log files will eventually fill up our containers if left unchecked. Enter logrotate to the rescue:

We are going to create a file named wordpress.logrotate with the following content:

/var/www/html/wp-content/debug.log
{
        su 1000 1000
        rotate 24
        copytruncate
        weekly
        missingok
        notifempty
        compress
}

This will gzip old logs daily and will delete even older logs. If you are not sure about the details, ChatGPT and Bard can explain exactly what each line does.

Note how we use again the uid and guid of the WordPress image.

Let’s mount this file into our WordPress containers, by adding a line to their volume clause:

volumes:
  - ./wp1fs:/var/www/html
  - ./wordpress.logrotate:/etc/logrotate.d/wordpress

volumes:
  - ./wp2fs:/var/www/html
  - ./wordpress.logrotate:/etc/logrotate.d/wordpress

Docker compose recap

We now have the following docker-compose.yml file:

version: "3.8"

name: droplet

networks:
    net1:
    net2:

volumes:
  db1volume:
  db2volume:

services:

  db1:
    image: mysql:8.2.0
    networks:
      - net1
    restart: unless-stopped
    expose:
      - "3306"
    volumes:
      - db1volume:/var/lib/mysql
      - ./disable-perf-schema.cnf:/etc/mysql/conf.d/disable-perf-schema.cnf
    environment:
      MYSQL_ROOT_PASSWORD: wp1_root_pass
      MYSQL_DATABASE: wp_db1
      MYSQL_USER: db1_user
      MYSQL_PASSWORD: db1_pass
    command: "mysqld --character-set-server=utf8mb4 --collation-server=utf8mb4_unicode_ci --performance-schema-instrument='%=OFF' --innodb-buffer-pool-size=32M"

  db2:
    image: mysql:8.2.0
    networks:
      - net2
    restart: unless-stopped
    expose:
      - "3306"
    volumes:
      - db2volume:/var/lib/mysql
      - ./disable-perf-schema.cnf:/etc/mysql/conf.d/disable-perf-schema.cnf
    environment:
      MYSQL_ROOT_PASSWORD: wp2_root_pass
      MYSQL_DATABASE: wp_db2
      MYSQL_USER: db2_user
      MYSQL_PASSWORD: db2_pass
    command: "mysqld --character-set-server=utf8mb4 --collation-server=utf8mb4_unicode_ci --performance-schema-instrument='%=OFF' --innodb-buffer-pool-size=32M"

  wp1:
    image: wordpress:latest
    networks:
      - net1
    depends_on:
      - db1
    user: 1000:1000
    restart: unless-stopped
    expose:
      - "80"
    volumes:
      - ./wp1fs:/var/www/html
      - ./wordpress.logrotate:/etc/logrotate.d/wordpress
    ports:
      - "8101:80"
    environment:
      WORDPRESS_DB_HOST: db1:3306
      WORDPRESS_DB_NAME: wp_db1
      WORDPRESS_DB_USER: db1_user
      WORDPRESS_DB_PASSWORD: db1_pass
      WORDPRESS_DB_COLLATE: utf8mb4_unicode_ci
      WORDPRESS_DEBUG: true

  wp2:
    image: wordpress:latest
    networks:
      - net2
    depends_on:
      - db1
    user: 1000:1000
    restart: unless-stopped
    expose:
      - "80"
    volumes:
      - ./wp2fs:/var/www/html
      - ./wordpress.logrotate:/etc/logrotate.d/wordpress
    ports:
      - "8102:80"
    environment:
      WORDPRESS_DB_HOST: db2:3306
      WORDPRESS_DB_NAME: wp_db2
      WORDPRESS_DB_USER: db2_user
      WORDPRESS_DB_PASSWORD: db2_pass
      WORDPRESS_DB_COLLATE: utf8mb4_unicode_ci
      WORDPRESS_DEBUG: true

We can start this with docker compose up (we must first cd into the same directory as the .yml file).

We can see if it’s running with docker compose ls, and we can see the containers with docker container ls.

We can inspect memory usage with docker stats.

We can stop the containers with docker compose down.

If we also want to wipe the database volumes and start over, we can do docker compose down -v (DESTRUCTIVE!!!).

We can go into the shell of the first database with:

docker exec -it droplet-db1-1 bash

And then, we can go into the mysql console with

mysql -u root -pwp1_root_pass

We can go into the shell of the first WordPress with:

docker exec -it droplet-wp1-1 bash

If we need to, we can install wp-cli using instructions from https://wp-cli.org/. The copy of wp-cli will not be persisted into the container across restarts. (Note: it’s possible to add special containers with wp-cli pre-installed, but again this is out of scope of this article. For more information, see the CLI images here.

DaaS (Docker-as-a-Service)

We don’t want to have to issue docker compose up every time the server starts, and docker compose down every time the server stops. Let’s create a systemd unit, so that it runs as a service.

We’ll create a file named /etc/systemd/system/docker-compose.service with the following carefully crafted contents:

[Unit]
Description=A bunch of containers
After=docker.service
Requires=docker.service

[Service]
Type=oneshot
RemainAfterExit=yes
User=yourusername
ExecStart=/bin/bash -c "docker compose -f /home/yourusername/docker-compose.yml up --detach"
ExecStop=/bin/bash -c "docker compose -f /home/yourusername/docker-compose.yml stop"

[Install]
WantedBy=multi-user.target

• Replace yourusername with your username (duh!).
• Replace the description with something less silly (optional).
• Note how we only start this service after the docker service starts.
• Note that we do a --detach. This will start the containers in the background and exit, without showing the logs of all the containers in the standard output.

We can now start the service with

sudo service docker-compose up

And stop it with

sudo service docker-compose down

If we want to see the logs of all the containers, we can type

docker compose logs -f

We should now be able to do curl http://127.0.0.1:8101 and see the HTML of the front page of the first WordPress.

The reverse proxy

The database and WordPress containers are running, but they are not yet exposed to the outside world. To do this, we are going to use nginx as a reverse proxy.

The reverse proxy will:

• handle all the redirects that we need
• expose the apache2 servers to the outside world
• handle the TLS encryption

First we setup Let’s Encrypt. How to do this is beyond the scope of this article. You can look here for a good introduction.

The bottom line is that certbot must be installed, and the following public and private certificate files must exist on your server (host):

/etc/letsencrypt/live/example1.com/fullchain.pem
/etc/letsencrypt/live/example1.com/privkey.pem
/etc/letsencrypt/live/example2.com/fullchain.pem
/etc/letsencrypt/live/example2.com/privkey.pem

These files are actually symlinks to the latest certificate issued. This is all handled by certbot.

Let’s start to create an nginx config file, which we will place in /etc/nginx/sites-available/reverse-proxy.conf.

We are going to enter several server stanzas, remembering that nginx will use the first one that matches in order from top to bottom.

Redirects from http to https

First, we want any unencrypted requests to port 80 to do a soft redirect to our https://www. sites.

server {
    listen       80;
    listen       [::]:80;
    server_name example1.com;
    return 302 https://www.example1.com$request_uri;
}

server {
    listen       80;
    listen       [::]:80;
    server_name example2.com;
    return 302 https://www.example2.com$request_uri;
}

The first listen statement is for IPv4, and the second is for IPv6. We redirect to the TLS site, preserving the path segment of the request URI.

Proxy forwarding

Next we are going to enter the stanza that handles the actual site content:

server {
    listen      443 ssl;
    listen      [::]:443 ssl;
    server_name www.example1.com;

    ssl_certificate /etc/letsencrypt/live/example1.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/example1.com/privkey.pem;
    include /etc/letsencrypt/options-ssl-nginx.conf;

    location / {
        proxy_pass http://127.0.0.1:8101/;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

server {
    listen      443 ssl;
    listen      [::]:443 ssl;
    server_name www.example2.com;

    ssl_certificate /etc/letsencrypt/live/example2.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/example2.com/privkey.pem;
    include /etc/letsencrypt/options-ssl-nginx.conf;

    location / {
        proxy_pass http://127.0.0.1:8102/;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

Again, we are listening for 443 (the TLS port) on both IPv4 and IPv6.

Notice how we only listen for requests to the www. subdomain here.

We use the TLS certificates first, then we specify the reverse proxy in the location / section.

We forward each site to the correct port that we exposed with docker (8101 and 8102 in this case).

We also set some X- headers. This is so that the PHP server knows some details about the client.

Redirects from all subdomains to www

Finally, we want requests from https://example1.com, or from ay other subdomain, such as https://foo.example1.com, to redirect to our www. subdomain:

server {
    listen 443 ssl;
    listen [::]:443 ssl;
    server_name .example1.com;

    ssl_certificate /etc/letsencrypt/live/example1.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/example1.com/privkey.pem;
    include /etc/letsencrypt/options-ssl-nginx.conf;

    location / {
        rewrite ^ https://www.example1.com permanent;
    }
}

server {
    listen 443 ssl;
    listen [::]:443 ssl;
    server_name .example2.com;

    ssl_certificate /etc/letsencrypt/live/example2.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/example2.com/privkey.pem;
    include /etc/letsencrypt/options-ssl-nginx.conf;

    location / {
        rewrite ^ https://www.example2.com permanent;
    }
}

Here we listen for any subdomain. Note the dot (.) prefix in the server_name.

We again use the TLS certificates, but this time we perform a redirect to the wwww. subdomain.

Administering our reverse proxy

When we are ready to enable our reverse proxy, we will create a symlink to sites-enabled:

sudo ln -s /etc/nginx/sites-available/reverse-proxy.conf /etc/nginx/sites-enabled/reverse-proxy.conf

We can test our syntax to see that it is correct with:

sudo nginx -t

And finally we can restart the nginx server with:

sudo service nginx restart

We can check the status of the server with:

sudo service nginx status

If everything is working correctly, and if the DNS records have had time to propagate, then we can visit our sites and run the famous WordPress installation process:

• https://www.example1.com/
• https://www.example2.com/

Emails

If only the above was enough. Sadly, our WordPress installations need a way to send emails, otherwise the webmaster experience is going to suck big time.

I say sadly, because setting up sendmail first on the host is relatively easy, but then setting up SMTP proxies in the WordPress containers is not something I am familiar with. Sorry guys, in the interest of keeping things simple, I’m going to cheat a little here. Here’s what I did:

• Install the free WP Mail SMTP plugin on both sites.
• Create an application-specific password in my google account.
• In the WordPress admin screens, go to: WP Mail SMTP → Mailer → Other SMTP.
• Enter the following settings:
  • SMTP Host: smtp.gmail.com
  • Encryption: SSL
  • SMTP Port: 465
  • Auto TLS: ON
  • Authentication: ON
  • SMTP Username: (my gmail address)
  • SMTP Password: (the application specific password that I just created).
• Hit Save Settings.
• Go to WP Mail SMTP → Tools and send a test email.

If everything works, then WordPress and its plugins can now send emails. But it will only be able to send email into spam folders, until we add a Sender Policy Framework (SPF) record to our DNS entries:

The above TXT records tell recipients to treat all emails coming from servers pointed to by the A or MX record of your domains as safe, and others as potentially suspicious. Again, use your favorite AI chatbot to constuct an SPF record that matches your needs.

Nothing more permanent than a 301 redirect

If all works, it’s now time to turn the soft redirects into permanent (hard) redirects. Edit the reverse proxy config and change any 302 redirects to 301. Any browsers visiting your site will cache these redirects for eternity.

It’s also now a good time to increase the Time-to-Live of all the DNS records to something like 4 hours, or 14400 seconds.

Backups

You would think that by now you’re finished, but you’d be wrong!

Any IT technician worth their salt knows that they must backup, and backup often.

First, turn off the server or droplet and take a full backup, snapshot, or whatever. Future you will thank you.

Then, let’s see how we can take automated daily backups. We can either pay the hosting provider every month to do this for us, or we can spend a few minutes to set up a few cron jobs. Let’s be cheap and do it manually.

I have a raspberry Pi at home that is always on. It does various things like take backups, ping various services and email me if they are down, trigger wp-cron URLs, control crypto miners, run services I need such as my ticket system, and in general runs any other odd 24/7 task. You should also have one such low-power system. The great thing with Raspberry Pi is that it’s easy to take out the MicroSD and gzip it into a mechanical disk, so the backup mechanism itself is nicely backed up in its entirety. (Yo dawg, heard you like backups…)

We’ll now use our local always-on Linux system to take daily backups of our online filesystems and databases:

Local backups.sh script

First, let’s create a DB user that only has enough access to take backups from both databases, but no more:

Login to the MySQL consoles of each database and create a wp_bu user that will do backups:

CREATE USER 'wp_bu'@'localhost' IDENTIFIED BY 'SOMESTRONGPASSWORD';
GRANT SELECT, LOCK TABLES ON wp_db1.* TO 'wp_bu'@'localhost';

CREATE USER 'wp_bu'@'localhost' IDENTIFIED BY 'SOMESTRONGPASSWORD';
GRANT SELECT, LOCK TABLES ON wp_db2.* TO 'wp_bu'@'localhost';

We only need SELECT, but since we want to call mysqldump with the --single-transaction argument, we’ll also need to grant the LOCK TABLES permission. No point in having an ACID database if we’re going to take backups of an inconsistent state now, is there?

We’ll now create a bash shell script that does our daily backups. Let’s place it in our local backup server and call it backups.sh:

#!/bin/bash

# ensure dirs exist
mkdir -p /path-to-backups/cache/wp{1,2}volume /path-to-backups/server

# download DBs to SQL files
ssh -t server "docker exec droplet-wpdb-1 nice -n 19 mysqldump -u wp_bu -pSOMESTRONGPASSWORD --no-tablespaces --single-transaction wp_db1 | nice -n 19 gzip -9 -f" >/path-to-backups/server/wp_db1-`date --rfc-3339=date`.sql.gz
ssh -t server "docker exec droplet-wpdb-2 nice -n 19 mysqldump -u wp_bu -pSOMESTRONGPASSWORD --no-tablespaces  --single-transaction wp_db2 | nice -n 19 gzip -9 -f" >/path-to-backups/server/wp_db2-`date --rfc-3339=date`.sql.gz

# download wp-content files to backup cache
rsync -aq server:~/wp1fs/* /path-to-backups/cache/wp1volume
rsync -aq server:~/wp2fs/* /path-to-backups/cache/wp2volume

# Zip downloaded wp-content files
zip -r9q /path-to-backups/server/wp1-`date --rfc-3339=date`.zip /path-to-backups/cache/wp1volume -x "**/GeoLite2*" -x "**/GeoIPv6.dat"
zip -r9q /path-to-backups/server/wp2-`date --rfc-3339=date`.zip /path-to-backups/cache/wp2volume -x "**/GeoLite2*" -x "**/GeoIPv6.dat"

# prune old DB and FILE backups from local backups
cd /path-to-backups/server && ls -1tr | head -n -30 | xargs -d '\n' rm -rf -

Again, a lot goes on here. Let’s unpack:

• The script creates directories server and cache under /path-to-backups. Replace this path with something that points to the directory where you want to keep your backups.
• We then ssh to the host using the -t argument because we are in a headless environment (cron). We issue a docker exec command into our databases. Notice how we do not use the -it arguments to docker exec, since this is a headless command (no TTY attached). The command is a mysqldump command that uses the credentials we just created to export the databases in a single transaction each. The SQL output is compressed with maximum compression (-9) and the binary output of gzip is forced (-f) into the standard output, which is then sent over the ssh connection. In our local backups server, we redirect this compressed stream into an .sql.gz file. The file name starts with wp_db1- and includes the current date in YYYY-MM-DD notation. (RFC 3339 is my idea of a perfect date, btw). The --no-tablespaces argument is need in MySQL 8.0.21 and later, otherwise you’ll need the PROCESS global permission. (Unless you are using tablespaces you don’t need it, hence the argument --no-tablespaces.) Notice that we make sure to be nice to other running processes because we don’t want to impact the performance of the web server with our backups. 19 is the idle CPU priority.
• We then use rsync with the quiet (-q) and archive (-a) flags to copy the files of our WordPress installations into our cache/wp1volume and cache/wp2volume directories. The advantage of using rsync is that only changes to these directories will be transferred.
• We then create a zip file for each of these directories. We name the zip files with the prefixes wp1- and wp2- followed again by our idea of a perfect date. Many WordPress plugins include a database of IPs mapped to geographical locations. These files are large and can be found online. If we don’t want to save these, we can exclude them (-x flag), but this is optional.
• Finally we list the files we created (both .sql.gz and .zip files) and we only keep the last 30, deleting any older ones. Since we have two files for each of two databases, this will retain daily backups for the last week or so.

Make the script executable with

chmod +x backups.sh

We run the script once, and we check the .sql.gz files using zless and the zip files with unzip -l.

Once we are certain that all data is backed up by the script, we add it to the crontab. Edit the crontab with crontab -e and add the line:

20 4 * * * /bin/bash /home/yourusername/backups.sh

This will execute the backups every day at 4:20 in the morning.

Checking the backups

The server works and is fully backed up. You would think that you’re done by now. That’s where you’d be wrong again!

Having backups and not checking them regularly is worse than not having backups at all: You are being lulled into a false sense of security. You may act precariously, thinking that you can always go back to the last backup. However, all backup mechanisms can fail, for any number of reasons.

What I do, is I’ve set up a weekly reminder in my Google calendar to check the backups. It only takes half a minute per week to ssh into my backup server and do an ls -l, thus ensuring that the latest backups exist, and their file size is what I’d expect. I keep old backups for about a week, hence the weekly reminder.

I also have another reminder every three months, to backup the MicroSD of my Raspberry Pi backup server. Once every three months, I shutdown the Pi, take out the MicroSD, put it into my work PC, and copy the entire image into a file, stored on my mechanical disk:

sudo dd if=/dev/sdf of=/mnt/bu/rpi-backup-`date --iso-8601=date`.img bs=4096 conv=sync,noerror status=progress
gzip -9 /mnt/bu/rpi-backup-`date --iso-8601=date`.img

Only once I have this process setup I can sleep at night.

Are we finished yet?

By now you would think that we’re not finished yet, and that there’s more things to do. That’s where you’d be wrong!

And for anyone wondering, example1.com is actually https://www.dashed-slug.net and example2.com is actually this blog, https://www.alexgeorgiou.gr. There’s also a plain nginx container in there that serves static HTML files at https://wallets-phpdoc.dashed-slug.net .

My config is actually a little bit more complex than the one discussed above. To save some more server memory, I had to put both databases into the same MySQL container, and set up two different DB users with access restricted to each respective database. But you shouldn’t do this at home, because isolation!

This article is being served by the containers I discussed here, and will be backed up early tomorrow morning, via the mechanism I shared with you above. Which is pretty meta, if you think about it!

I never expected to compose such a long, self-contained article on containers and docker compose. But now it’s finished and I can hardly contain my excitement!

Thanks for sticking to the end. Hope you enjoyed.

The post 📦 Two dockerized WordPress sites, with Let’s Encrypt, logging, SMTP relay, controlled by a systemd service, and daily backups appeared first on Alexandros Georgiou.

In my dream, I was programming a custom SQL query for some WordPress plugin. The query was an INSERT statement, that simply passed a vector of strings into a table row of VARCHAR columns. I remember the code vividly, but table/column names were not important so I don’t remember all of them. There was a first name column, and a last name column. It must have looked something like:

	global $wpdb;
	
	$query = $wpdb->prepare(
		"INSERT INTO sometable(
			firstname,
			lastname,
			arg1,
			arg2,
			arg3,
			arg4
		)
		VALUES(
			%s,
			%s,
			%s,
			%s,
			%s,
			%s
		)"
	);

I had dev-tested this in my dream and it was working fine. Until I once passed a string with two words, separated by a space character, into one of those arguments. Then I saw some error in the SQL logs. Turns out, in my dream, the SQL server was happy to accept one-word strings, even without surrounding quotes!!! Kind of like the syntax for strings in CSV. (I know, I have the wildest dreams!)

And to make things even weirder, for some reason, the prepare() function did not add these quotes; I had to supply them myself. Why, prepare function? WHY? You had ONE job!

Oh well, I thought to myself. Easy fix. I will surround the %s placeholders with double quotes myself. But as I started to do this, the list of %s became longer and longer. There must have been like 20 or 30 arguments in that list. Not a job to do by hand.

Naturally, all I had to do is use my editor to auto-replace the %s, with "%s". But then, again, complications arose. The placeholders in the prepare statement were not in the usual sprintf syntax. Instead of %s, they conveniently were the Unicode characters for cake, muffin, and other assorted confectioneries. How did I not notice this before?

Oh well, I must have been hungry, because it seemed fairly reasonable at the time, that the prepare statement accepted placeholders like cupcakes, pies, bagels and pancakes. So now the VALUES vector looked more like:

	VALUES(
		?,
		?,
		?,
		?,
		?,
		?,
		?,
		?,
		?,
		?,
		?,
		?,
		?,
		?,
		?,
		?,
		?,
		?
	)

I didn’t stop for a second to think about how weird this is, or even to check the wpdb manual again. Instead, I proceeded to wrap these tasty treats with double quotes.

But lo and behold! Another thing not turning out as usual! The IDE editor had trouble with Unicode characters. I would paste in a cupcake character into the search and replace box, and it would turn into an escape-code. In this case it would have been \U1F95E. (No, I do not remember the exact code from the dream, I had to look it up.)

As is usual with dreams, I did not stop to think why my IDE doesn’t have Unicode support in 2021. Instead, I shrugged it off as another odd thing that just happened, because reasons. I copied the query into another editor, and started replacing the tasty string placeholders, one by one, in that other editor.

That’s when my girlfriend woke me up. It was Monday morning.

She was somewhat upset, because she had to go to work and she was running late. I, on the other hand, was looking forward for work. After all, who doesn’t like cupcakes, pies, bagels and pancakes?

I know she reads my blog, so I just want to wish her, wholeheartedly, a very, very nice and easy day at work. \U2665

And to anyone else reading this, sorry for wasting your time with my nonsense!

The post 🧁 Blueberry cupcake string placeholders appeared first on Alexandros Georgiou.

Introduced in 3.0, the multisite feature feels a little awkward when developing code, partly because things you take for granted in single-site installs are simply not there, partly because other things are unnecessarily different, partly because of the shifting terminology that has evolved over time, and partly because of the significantly less documentation, compared to that available on single-site features. Moreover there are significantly less articles about it out there, since most people care about single-site installs.

But, it works! After all, last time I checked, wordpress.com was up and running! The fact that people were able to extend WordPress so drastically in a way that actually works, is impressive to say the least. I can only imagine how hard it must have been. The idea is that you can make your WordPress behave just like wordpress.com, where users can create their own site.

So yes, some things about network-activated plugins on multisite suck, but they don’t suck to the point of being unusable. You just need to learn a few tricks. Fortunately, you came across this article, so all will become clear. Or will they?

Some basic terminology

A multisite (aka MS) install is sometimes also called a network. A network can have a multitude of sites, and sites can have many blogs. Confusingly, site can also mean blog besides network. And network does not mean what we normally mean in IT, it means a collection of sites or multi-sites, depending on who you ask. And a blog of course is not necessarily an actual weblog, but can be any type of site.

To add to the fun, in the past the multisite feature was named multiuser (or WPMU, or MU for short). Presumably this was changed because multiuser is a stupid name for this feature: all WordPress installations can have multiple users. But you do need to be aware of all the terms out there, because you will come across them at some point.

To paraphrase an old saying,

There are only two hard problems in computer science, cache invalidation and naming WordPress things.

Users who create blogs, or sites, or whatever (sigh!) on your multisite are administrators of their respective sites, and you, the owner of the network are a network admin, also known as a super admin. The network admin can administer global settings for the entire network from the network admin menu.

What does network activated actually mean?

Themes and plugins can either be:

• activated on individual blogs by administrators, if the administrators have the capability to do so, or
• network-activated once, site-wide, by the network admin, making them available to all blogs.

Custom DB tables

Most tables in the DB are duplicated for each blog, where the table name prefix contains the blog ID, so that, for example, options for blogs 3 and 4 are safely stored in tables wp_3_options and wp_4_options respectively. This allows for blog administrators to activate and configure their plugins separately for their blogs. As long as they activate the plugins themselves, everything should work just fine for most plugins, out of the box.

If you are maintaining custom DB tables, these will need some extra coding work. There are two ways to do this: Either

• add a blog_id column to your rows, and then filter your SQL queries by blog_id=get_current_blog_id(), or
• create separate tables for each blog when your plugin activates, by binding with the register_activation_hook() function, and also create tables whenever a new blog is created after your plugin has been activated, by binding to wpmu_new_blog.

You can read more about this here:

How To Properly Create Tables In WordPress Multisite Plugins

To network activate, or not to network activate?

Depending on what your plugin actually does, you might want to have parts of it operate site-wide. This often makes sense, but know that in doing so you might be opening a big can of worms. The network admin area introduces its own set of actions and filters, its own menu structure, its own URL structure, a somewhat lacking settings API where you have to do some things manually, and you will have to think about how your wp_cron hooks work, new user capabilities, and different plugin activation code.

The function is_multisite() tells you whether the WordPress install is multisite, but it tells you nothing about whether your plugin is activated for the network or whether it was activated at the blog level.

To find out whether your plugin is network activated or not, first import the right function:

if ( ! function_exists( 'is_plugin_active_for_network' ) ) {
    require_once( ABSPATH . '/wp-admin/includes/plugin.php' );
}

Then, you can do this:

if ( is_plugin_active_for_network( 'myplugin/myplugin.php' ) ) { // do stuff }

assuming that your plugin’s slug is myplugin. The function will always return false on single-site installs.

So many options…

If some options must apply to the entire network, you will need to expose a menu of panels with those options to the network administrator.

Know your DB options

Those options can be thought of as “global” for a site (aka network), and they ought to be stored in the wp_sitemeta table. The table name is programmatically available as $wpdb->sitemeta. It is just like the wp_options table, but totally different: Columns option_name and option_value correspond to meta_key and meta_value. If you’re wondering about the site_id column, no, it’s not an identifier to individual blogs, it’s a unique identifier to a site, because, yes, you can have several sites on one network, each with several blogs.

:s/_option/_site_option/

These site meta options are accessed not by the usual functions get_option() and friends, but by get_site_option(), update_site_option(), add_site_option() and delete_site_option().

Option-related capabilities

You might be interested in the manage_network_options capability that is normally granted to Super Admins. In fact, have a look at Roles and Capabilities in the Codex to make sure you know about all of the manage_network_* capabilities, as well as the *_sites capabilities. Essential reading if you’re a network admin.

Updating site options

Know that you will have to do things differently when creating admin forms for network-wide options. In a nutshell:

• you need to hook to the network_admin_menu action rather than admin_menu.
• your HTML forms need to have a different action attribute,
• you need to bind a submit handler to:
  • check for the admin nonce,
  • actually save the settings to the DB, and
  • redirect back to the right admin panel.
• Use network_admin_url() wherever you’d normally use admin_url().

I will not go through all of this detail here, as it is explained very well in this rare article:

Using the WordPress Settings API with Network Admin pages

I find this article tells you all that you need to know about how to actually save site meta, but if you want to read more, you can have a look at the official documentation, which currently simply links to here and here.

Getting hooked to site-wide options yet? Not to worry, there’s more!

Keep in mind that there exists a multitude of hooks that are specific to network administration. For example, to do various custom stuff to a site-wide option before saving it to the DB, do not bind to pre_update_option_{$option_name}, but to pre_update_site_{$option_name}.

Set option values via the terminal like a 1334 h@x0r

If you’re like me, you probably have set up your build process to auto-inject options to your dev environment, using wp-cli. Instead of

 wp option update option_name option_value

do something like this instead:

wp network meta set 1 option_name option_value

where 1 is the number of your multisite environment.

How to nag the right admin

To show notices to the network admin, do not bind to admin_notices, instead bind to network_admin_notices.

The surprising secret argument of the activation hook that nobody knew about!!!

Apologies, when I’m blogging I sometimes go into full SEO mode. Anyhow…

For your activation handler to work, you will first need to bind a function with register_activation_hook(), as usual. It turns out that your activation handler can take a parameter that tells you whether the plugin is being network-activated or not.

Here’s a handy way I like to use to create options that can either be global on the multisite level, or bound to the current blog, depending on whether your plugin was network-activated or activated on a single blog:

function activation_hook( $network_active ) {
    call_user_func(
        $network_active ? 'add_site_option' : 'add_option',
        'option_name',
        'option_value'
    );
}
register_activation_hook( __FILE__, 'activation_hook' );

Clean up after yourself!

Remember to do the same in your uninstall.php. You do clean up after yourself, don’t you? Of course you do, you’re a developer, not a filthy pig.

Remember, you will not be able to use is_plugin_active_for_network(), because by the time the uninstall code runs, the plugin should have already been deactivated. Since the plugin is being uninstalled completely, you can do something like the following, just to be on the safe side:

// delete from site meta
delete_site_option( 'option_name' );

// also delete from options table for all blogs
global $wpdb;
foreach ( $wpdb->get_col( "SELECT blog_id FROM $wpdb->blogs" ) as $blog_id ) {
    switch_to_blog( $blog_id );
    delete_option( 'option_name' );
    restore_current_blog();
}

You will also likely want to delete any custom tables you may have created. The trick here is to iterate over all the blogs and let WordPress choose the right DB prefix.

foreach ( $wpdb->get_col( "SELECT blog_id FROM $wpdb->blogs" ) as $blog_id ) {
    switch_to_blog( $blog_id );
    $wpdb->query( "DROP TABLE IF EXISTS {$wpdb->prefix}mytable" );
    restore_current_blog();
}

If you have chosen the separate tables way, you should also hook a DROP TABLE query to the delete_blog hook:

function delete_blog_tables( $blog_id, $drop ) {
    if ( $drop ) {
        switch_to_blog( $blog_id );
        $wpdb->query( "DROP TABLE IF EXISTS {$wpdb->prefix}mytable" );
        restore_current_blog();
    }
}
add_action( 'delete_blog', 'delete_blog_tables' );

If on the other hand you have one table for all blogs, and your rows have a blog_id column, do something more in the tune of:

function delete_blog_tables( $blog_id, $drop ) {
    if ( $drop ) {
        $wpdb->query( "DELETE FROM {$wpdb->prefix}mytable WHERE blog_id = $blog_id" );
    }
}
add_action( 'delete_blog', 'delete_blog_tables' );

There! All clean now!

Cron

You will want to use that handy little foreach loop in more than just the uninstall script. For instance, suppose you’re using cron. If your plugin is network activated, cron will run once for the network, not once per blog. Assuming your cron handler needs to do stuff to each blog, you’d do something like:

function cron_handler( ) {
    if ( is_plugin_active_for_network( 'myplugin/myplugin.php' ) ) {
        global $wpdb;
        foreach ( $wpdb->get_col( "SELECT blog_id FROM $wpdb->blogs" ) as $blog_id ) {
            switch_to_blog( $blog_id );
            do_stuff();
            restore_current_blog();
        }
    } else {
        do_stuff();
    }
}
add_action( 'cron_hook', 'cron_handler' );

if ( false === wp_next_scheduled( 'cron_hook' ) ) {
    wp_schedule_event( time(), 'every_now_and_then', 'cron_hook' );
}

function do_stuff() {
    // do your stuff here
}

This way if your plugin runs network-wide, then your stuff is done on each one of the blogs on your multisite. But if the plugin is activated on the blog level, it does stuff only on the current blog.

Good stuff!

Super secret plugin header: Network

Edit: This plugin header seems to not be respected any more; perhaps this is why it is not documented. It is part of WordPress history.

Although you wouldn’t have guessed it from reading the relevant documentation, the plugin header, i.e. that special block of comments that you put at the top of your main plugin file, can have something to say about network activation. (A tiny hint is given in the Codex that such a header exists, although the documentation does not currently bother explaining what it does. After all, if everything was documented, where would the fun be?)

If your plugin is intended to be only network activated, and not activated on the blog-level in multi-sites, then add this line to your plugin’s header:

Network: True

Now WordPress will not give the activation option to mere blog admins.

Are you still with me?

Awesome! There you have it! Now you know all that I currently know about WordPress multisite and network activated plugins. Which is arguably not a lot. If you know more and feel like sharing, you’re free to comment below.

Hopefully you now have some grasp of the types of things you should be looking out for when you take your plugin for a ride into the wacky world of network activation.

Take care.

Alex

The post 🖧 The wacky world of network activated WordPress plugins in multisite appeared first on Alexandros Georgiou.

Versions

On my Ubuntu 16 installation (let’s call it example1.com) I have a project on this version of trac:

$ lsb_release  -d
Description:    Ubuntu 16.10
$ tracd --version
tracd 1.0.12

I had good(-ish) reasons to migrate the entire project to a copy on an Ubuntu 10 machine.

$ lsb_release -d
Description:    Ubuntu 10.04.4 LTS

Installing trac

These are the resources that you need to be aware of:

• https://trac.edgewall.org/wiki/TracOnUbuntu
• https://trac.edgewall.org/wiki/MySqlDb

I first installed trac via the old-releases.ubuntu.com repository.

$ sudo apt-get install trac

This installed an earlier version than the one I had.

$ tracd --version
tracd 0.11.7

Setting up the new (old) trac

Rather than upgrading the entire system with do-release-upgrade, I decided to work with this version.

You will need the python-mysqldb module on example2.com to access a MySQL database. If you’re using PostgreSQL the procedure should be similar. YMMV.

$ sudo apt-get install python-mysqldb

First, copy the assets of the project environment. This is a directory tree that you can copy over using rsync.

rsync -r example1.com:/path-to-trac-env example2.com:/path-to-trac-env

For simplicity we’ll keep everything the same: file directories, database name and database credentials, although you could change these. Your database settings are in the /path-to-trac-env/conf/trac.ini file. You want the database variable under the [trac] section, which should look something like:

[trac]

database = mysql://tracuser:tracpassword@localhost:3306/trac-env

You will want to create an empty MySQL database where your project will live. You will need the MySQL client on example2.com, so if you don’t have it, install it with:

sudo apt-get install mysql-client

You will then want to login as root

mysql -u root -p

and create the database, (using the utf8_bin collation)

CREATE DATABASE `trac-env` DEFAULT CHARACTER SET utf8 COLLATE utf8_bin;

and finally create the user:

GRANT ALL ON `trac-env`.* TO tracuser@localhost IDENTIFIED BY 'tracpassword';

Exit the MySQL client with Ctrl-D and import a standard SQL dump of your database from example1.com. For instance, if you like one-liners, you might do this on example2.com:

ssh example1.com "mysqldump -u tracuser -ptracpassword --single-transaction trac-env | gzip -9" | zcat | mysql -u tracuser -ptracpassword trac-env

Nasty hack FTW

Now start tracd and visit the installation via your web browser. You should see an error like this:

 Trac detected an internal error:

ValueError: timestamp out of range for platform time_t

This is because all timestamps in this newer version of trac are in microseconds, rather than seconds. Here is a (somewhat) relevant ticket.

I went ahead and hacked the DB thusly:

update ignore attachment set time = floor( time / 10000000);
update ignore auth_cookie set time = floor( time / 10000000);
update ignore revision set time = floor( time / 10000000);
update ignore ticket set time = floor( time / 10000000);
update ignore ticket set changetime = floor( changetime / 10000000);
update ignore ticket_change set time = floor( time / 10000000);
update ignore version set time = floor( time / 10000000);
update ignore wiki set time = floor( time / 10000000);

These are all the timestamp columns in the DB. Dividing by a million converts millionths of a second to seconds and the floor function makes sure that the result is still an integer.

The ignore argument is there only because I had one single collision in one ticket comment. Needless to say, this is a nasty hack, so don’t rely on it too much.

But, for my purposes, “It Works”!

The post How to migrate trac MySQL-based project from trac 1.0.12 to trac 0.11.7 appeared first on Alexandros Georgiou.

The auto_increment problem and its symptoms

When you export the WordPress database and then import it again, either via phpmyadmin or via mysqldump and the mysql CLI, all sorts of things can (and often will) go wrong. This can be understandably very stressful, especially on a live system. Please take a deep breath and read on.

I did a dump of my (fortunately development) environment and then imported it again. At first glance, all was working perfectly.

Then, all of a sudden I noticed that the Administrator user had no rights to create posts or pages. The usual Publish button was replaced with Submit for review.

Naïvely my first thought was to install a plugin to fix roles and capabilities. Sure enough, the admin user had no right to create posts or pages. When I tried to give those rights, I saw the following in my logs:

PHP message: WordPress database error Duplicate entry '0' for key 'PRIMARY' for query INSERT INTO `wp_usermeta` (`user_id`, `meta_key`, `meta_value`) VALUES (1, 'wp_capabilities', 'a:1:{s:13:\"administrator\";b:1;}') made by require_once('wp-admin/admin.php'), do_action('users_page_users-user-role-editor'), User_Role_Editor->edit_roles, Ure_Lib->editor, Ure_Lib->process_user_request, Ure_Lib->permissions_object_update, Ure_Lib->update_user, WP_User->add_role, update_user_meta, update_metadata, add_metadata

(I have debug logs enabled in my development environment. If you’re in a production environment you might not see this.)

Why would a primary key be set to 0 you ask? A quick glance at the structure of the wp_usermeta table via phpmyadmin reveals that the primary key column had no auto_increment flag.

SQL INSERT statements from various plugins were inserting rows in various tables with the primary key being undefined (and therefore set to a default of 0). Since primary keys have a unique constraint, attempting to do a second insert to the same table fails, causing all sorts of havoc.

For some reason the auto_increment flag had not been preserved when I re-imported the SQL dump. Everything else seemed to be in order though. I did not investigate why this happened but decided to simply fix this.

Coding is the solution

By now I could see the front-end but was not able to login to the admin interface any more. Any INSERT query to the database, including those that store session information upon login, were failing. As I had quite a lot of tables, I decided not to do this manually, but to write a generic script.

As a side-note, the script needs to connect with the NO_ZERO_DATE SQL mode. WordPress uses a lot of DATETIME fields with a default value of 0000-00-00 00:00:00 and this script will be very unhappy if this mode is not set.

Pseudocode

for all tables in database
    get the primary key column's name and type
    get the next available primary key value
    change the row with zero primary key so it has the next available primary key
    set the auto_increment flag to the primary key column

Note: The above assumes that all the primary keys are numeric. YMMV.

What to do:

Next is a PHP listing of the above solution. Here’s what to do:

1. Check to see that your issue is actually one of missing auto_increment flags. This script will only repair this particular error.
2. Check to see that all your primary keys are numeric. There shouldn’t be an issue if some aren’t but you might have to hack the code manually or go update the structure of those tables via phpmyadmin.
3. Change the host, dbname, username and password in the code to those that match your system.
4. Backup your database (I guess you already have a backup and that’s what caused the issue, but still, you want to be able to go back if something goes wrong when running this.) You are solely responsible for any damages including data loss from running this script. Don’t blame me for corrupting your data please. Read and understand the code first!

The PHP script

Save this in a file, take another deep breath, and run it via the PHP CLI. I hope it solves your MySQL woes. Good luck buddy.

<?php

// change these settings
$servername = 'localhost';
$username = 'dbuser';
$password = 'password';
$db = 'database';

// connect
$conn = new mysqli($servername, $username, $password);
try {
    $conn = new PDO("mysql:host=$servername;dbname=$db", $username, $password, array(PDO::MYSQL_ATTR_INIT_COMMAND => 'SET sql_mode="NO_ZERO_DATE"') );
    $conn->setAttribute(PDO::ATTR_ERRMODE, PDO::ERRMODE_EXCEPTION );
    echo "Connected successfully";
} catch(PDOException $e) {
    exit( "Connection failed: " . $e->getMessage() );
}

// get all table names
$stm = $conn->prepare('SHOW TABLES');
$stm->execute();
$table_names = array();
foreach ( $stm->fetchAll() as $row ) {
    $table_names[] = $row[0];
}

// for all tables
foreach ( $table_names as $table_name ) {
    echo "\nRepairing table $table_name...\n";

    // get the primary key name
    $stm = $conn->prepare( "show keys from $table_name where Key_name = 'PRIMARY'" );
    $stm->execute();
    $key_name = $stm->fetch()['Column_name'];

    // get the primary key type
    $stm = $conn->prepare( "show fields from $table_name where Field = '$key_name'" );
    $stm->execute();
    $key_type = $stm->fetch()['Type'];

    // if there is a primary key
    if ($key_name) {
        echo "Primary key is $key_name\n";

        try {
            // if auto_increment was missing there might be a row with key=0 . compute the next available primary key
            $sql = "select (ifnull( max($key_name), 0)+1) as next_id from $table_name";
            $stm = $conn->prepare( $sql );
            echo "$sql\n";
            $stm->execute();
            $next_id = $stm->fetch()['next_id'];

            // give a sane primary key to a row that has key = 0 if it exists
            $sql = "update $table_name set $key_name = $next_id where $key_name = 0";
            echo "$sql\n";
            $stm = $conn->prepare( $sql );
            $stm->execute();

            // set auto_increment to the primary key
            $sql = "alter table $table_name modify column $key_name $key_type auto_increment";
            echo "$sql\n";
            $stm = $conn->prepare( $sql );
            $stm->execute();

        } catch (PDOException $e) {
            echo "\n\nQuery: $sql\nError:" . $e->getMessage() . "\n\n";
        }
    } else {
        echo "No primary key found for table $table_name.\n";
    }
}
echo "\n\nFinished\n";
$conn = null;

If I have helped you get your site up and running, you can donate a few Satoshis at: bc1qjkgp8u2jwy2n9k20avjweuy7etsjfpfplvf99q

The post auto_increment flag repair on primary keys of a WordPress MySQL database appeared first on Alexandros Georgiou.

Some things to note about dismissible notices

Don’t you just hate how this functionality has still not made it into core? Legend has it that dismissible notices were introduced back in WordPress 4.2, but that only means that when you click the little “x” at the top right, the notice box becomes hidden. The way to enable this is that you add a .is-dismissible class into your notice’s markup:

<div class="notice notice-warn is-dismissible">your message here</div>

And that hides the box. Until the next page refresh. This is not only annoying, it also goes against the WordPress.org guidelines:

Upgrade prompts, notices, and alerts should be limited in scope and used sparingly or only on the plugin’s setting page. Any site wide notices or embedded dashboard widgets must be dismissible. Error messages and alerts should include information on how to resolve the situation, and remove themselves when completed.

So for those of us aspiring to be hosted on WordPress.org it’s a necessity, rather than a luxury feature, to be able to let the user dismiss notices persistently.

Requirements analysis

WordPress tradition has it that you store an option in the database. That way you know not to show the same notice again. But this is something that you have to do over and over again, so it’s exactly the kind of thing that you want to include in all your code as a library. You want something that can be easily called from wherever, so the tried and true singleton pattern will do. You need the ability to be able to assign a slug to your notice, so you know how to store it in the options table. But you also want to be able to show the occasional non-dismissible notice. Finally, let’s be nice and clean up after ourselves. The options will be deleted when our plugin is uninstalled.

Let’s do this!

Writing code with class

We need something that can be included from our plugin (or theme). Let’s make a singleton class that can hold arrays of different types of notices (success, info, warn, error):

<?php

// don't load directly
defined( 'ABSPATH' ) || die( '-1' );

if ( ! class_exists( 'MyPlugin_Admin_Notices' ) ) {

    class MyPlugin_Admin_Notices {

        private static $_instance;
        private $admin_notices;
        const TYPES = 'error,warning,info,success';

        private function __construct() {
            $this->admin_notices = new stdClass();
            foreach ( explode( ',', self::TYPES ) as $type ) {
                $this->admin_notices->{$type} = array();
            }
        }

        public static function get_instance() {
            if ( ! ( self::$_instance instanceof self ) ) {
                self::$_instance = new self();
            }
            return self::$_instance;
        }
    }
}

MyPlugin_Admin_Notices::get_instance();

Nice. This is a useful bucket where we can throw in notices. They will be retrieved for rendering only later, when we will add code to the admin_notices action.

An API for entering notices from our code

For now, let’s add in some methods to our class for populating our notice arrays:

public function error( $message, $dismiss_option = false ) {
    $this->notice( 'error', $message, $dismiss_option );
}

public function warning( $message, $dismiss_option = false ) {
    $this->notice( 'warning', $message, $dismiss_option );
}

public function success( $message, $dismiss_option = false ) {
    $this->notice( 'success', $message, $dismiss_option );
}

public function info( $message, $dismiss_option = false ) {
    $this->notice( 'info', $message, $dismiss_option );
}

private function notice( $type, $message, $dismiss_option ) {
    $notice = new stdClass();
    $notice->message = $message;
    $notice->dismiss_option = $dismiss_option;

    $this->admin_notices->{$type}[] = $notice;
}

Notice the visibility of the functions. The four public functions that comprise our API all defer to the private function that does the data collection. We’ll let the user enter a message string, and optionally give a slug with the dismiss_option parameter. If set, this will be part of the database option’s slug.

Writing the markup

We have a mechanism for adding notices into our memory, now let’s dump them to the admin area as markup. This will happen on the admin_notices action, so first add this to the constructor:

add_action( 'admin_notices', array( &$this, 'action_admin_notices' ) );

and then let’s actually write the markup. I’ve chosen to show notices in decreasing levels of severity, hence the nested loops:

public function action_admin_notices() {
    foreach ( explode( ',', self::TYPES ) as $type ) {
        foreach ( $this->admin_notices->{$type} as $admin_notice ) {

            $dismiss_url = add_query_arg( array(
                'myplugin_dismiss' => $admin_notice->dismiss_option
            ), admin_url() );

            if ( ! get_option( "myplugin_dismissed_{$admin_notice->dismiss_option}" ) ) {
                ?><div
                    class="notice myplugin-notice notice-<?php echo $type;

                    if ( $admin_notice->dismiss_option ) {
                        echo ' is-dismissible" data-dismiss-url="' . esc_url( $dismiss_url );
                    } ?>">

                    <h2><?php echo "My Plugin $type"; ?></h2>
                    <p><?php echo $admin_notice->message; ?></p>

                </div><?php
            }
        }
    }
}

Note how we show a notice only if the DB does not have a corresponding option named myplugin_dismissed_$dismiss_option. We’ll need a mechanism to set that DB option when the user clicks to dismiss the notice. We will do this from JavaScript, making a call with that option name as a GET parameter, so that we know to set the correct database option.

Notifying the backend from the admin front

When a notice is dismissible, we output a data-dismiss-url attribute in the HTML. We’ll use that from JavaScript to make a call to that URL:

/**
 * Admin code for dismissing notifications.
 *
 */
(function( $ ) {
    'use strict';
    $( function() {
        $( '.myplugin-notice' ).on( 'click', '.notice-dismiss', function( event, el ) {
            var $notice = $(this).parent('.notice.is-dismissible');
            var dismiss_url = $notice.attr('data-dismiss-url');
            if ( dismiss_url ) {
                $.get( dismiss_url );
            }
        });
    } );
})( jQuery );

Pretty standard stuff. When a dismissible notice from our plugin is clicked on its .notice-dismiss, get the dismiss_url and call it. I guess I could have used a fancy framework like VanillaJS for this, but I chose plain old jQuery instead :-p

Don’t forget the usual enqueue script shenanigans:

public function action_admin_enqueue_scripts() {
    wp_enqueue_script( 'jquery' );
    wp_enqueue_script(
        'myplugin-notify',
        plugins_url( 'assets/scripts/myplugin-notify.js', __FILE__ ),
        array( 'jquery' )
    );
}

and add this to our constructor so the enqueuing will actually happen:

add_action( 'admin_enqueue_scripts', array( &$this, 'action_admin_enqueue_scripts' ) );

Perfect. Our little piece of JavaScript code now lives in the WordPress admin screens.

Setting the DB option

Now we’ll just need to catch the request on the PHP side and set a database option. Let’s do this on the admin_init action:

add_action( 'admin_init', array( &$this, 'action_admin_init' ) );

…and this is the code that will set an option in the database. Note how the name is constructed from the GET parameter in the request URL.

public function action_admin_init() {
    $dismiss_option = filter_input( INPUT_GET, 'myplugin_dismiss', FILTER_SANITIZE_STRING );
    if ( is_string( $dismiss_option ) ) {
        update_option( "myplugin_dismissed_$dismiss_option", true );
        wp_die();
    }
}

Once the option is set, we can just let WordPress die. No need to return the admin interface to the browser, this is just a background AJAX call.

Cleaning up after ourselves

Unfortunately, even in this day and age, many developers don’t think it’s important to clean up the trash they leave in the poor user’s database. This is even more infuriating when you consider that it rarely takes more than a couple of lines of code. Don’t be that guy. Create an uninstall.php file with the following content.

<?php
if ( defined( 'WP_UNINSTALL_PLUGIN' ) ) {
    global $wpdb;
    $wpdb->query( 'DELETE FROM wp_options WHERE option_name LIKE "myplugin_dismissed_%";' );
}

We can exploit the fact that we know the common prefix of all the dismissal DB options, and thus we can delete them all in one go, circumventing the delete_option() function altogether:

Expecting the unexpected

If you put together all of the above you already have a nice way to show persistent dismissible admin notices. But why stop there? We can hack away some more and make sure that any runtime errors in our code show up as notices too.

Imagine a clueless user sees your theme not working. Which do you prefer? To have to explain to them how to enable debugging and how to find and send you the logs from the wordpress unix directory on the host? Or do you simply ask them to copy the error on the screen and send it to you via email?

Observe this little hack that takes advantage of the PHP error reporting mechanism:

public static function error_handler( $errno, $errstr, $errfile, $errline, $errcontext ) {
    if ( ! ( error_reporting() & $errno ) ) {
        // This error code is not included in error_reporting
        return;
    }

    $message = "errstr: $errstr, errfile: $errfile, errline: $errline, PHP: " . PHP_VERSION . " OS: " . PHP_OS;

    $self = self::get_instance();
    switch ($errno) {
        case E_USER_ERROR:
            $self->error( $message );
            break;

        case E_USER_WARNING:
            $self->warning( $message );
            break;

        case E_USER_NOTICE:
        default:
            $self->notice( $message );
            break;
    }

    // write to wp-content/debug.log if logging enabled
    error_log( $message );

    // Don't execute PHP internal error handler
    return true;
}

Notice how this method is static, since we’d like to be able to call it from both dynamic and static contexts. We can now hook it up to PHP’s error reporting like so:

set_error_handler( array( 'MyPlugin_Admin_Notices', 'error_handler' ) );

and after your code ends, unhook it so as not to interfere with the WordPress core or other components:

restore_error_handler();

This will pop your error handler from a stack and return to whatever error handling mechanism was there before. Make a habit of surrounding your function bodies with these two lines, and you will know that whatever happens, you’ll at least get a visible user-friendly and developer-friendly error message on the admin screens.

Putting it all together

JS

/**
 * Admin code for dismissing notifications.
 *
 */
(function( $ ) {
    'use strict';
    $( function() {
        $( '.myplugin-notice' ).on( 'click', '.notice-dismiss', function( event, el ) {

            var $notice = $(this).parent('.notice.is-dismissible');
            var dismiss_url = $notice.attr('data-dismiss-url');
            if ( dismiss_url ) {
                $.get( dismiss_url );
            }
        });
    } );
})( jQuery );

PHP

<?php
if ( defined( 'WP_UNINSTALL_PLUGIN' ) ) {
    global $wpdb;
    $wpdb->query( 'DELETE FROM wp_options WHERE option_name LIKE "/* @echo slugus */_dismissed_%";' );
}

<?php
// don't load directly
defined( 'ABSPATH' ) || die( '-1' );

if ( ! class_exists( 'MyPlugin_Admin_Notices' ) ) {

    class MyPlugin_Admin_Notices {

        private static $_instance;
        private $admin_notices;
        const TYPES = 'error,warning,info,success';

        private function __construct() {
            $this->admin_notices = new stdClass();
            foreach ( explode( ',', self::TYPES ) as $type ) {
                $this->admin_notices->{$type} = array();
            }
            add_action( 'admin_init', array( &$this, 'action_admin_init' ) );
            add_action( 'admin_notices', array( &$this, 'action_admin_notices' ) );
            add_action( 'admin_enqueue_scripts', array( &$this, 'action_admin_enqueue_scripts' ) );
        }

        public static function get_instance() {
            if ( ! ( self::$_instance instanceof self ) ) {
                self::$_instance = new self();
            }
            return self::$_instance;
        }

        public function action_admin_init() {
            $dismiss_option = filter_input( INPUT_GET, 'myplugin_dismiss', FILTER_SANITIZE_STRING );
            if ( is_string( $dismiss_option ) ) {
                update_option( "myplugin_dismissed_$dismiss_option", true );
                wp_die();
            }
        }

        public function action_admin_enqueue_scripts() {
            wp_enqueue_script( 'jquery' );
            wp_enqueue_script(
                'myplugin-notify',
                plugins_url( 'assets/scripts/myplugin-notify.js', __FILE__ ),
                array( 'jquery' )
            );
        }

        public function action_admin_notices() {
            foreach ( explode( ',', self::TYPES ) as $type ) {
                foreach ( $this->admin_notices->{$type} as $admin_notice ) {

                    $dismiss_url = add_query_arg( array(
                        'myplugin_dismiss' => $admin_notice->dismiss_option
                    ), admin_url() );

                    if ( ! get_option( "myplugin_dismissed_{$admin_notice->dismiss_option}" ) ) {
                        ?><div
                            class="notice myplugin-notice notice-<?php echo $type;

                            if ( $admin_notice->dismiss_option ) {
                                echo ' is-dismissible" data-dismiss-url="' . esc_url( $dismiss_url );
                            } ?>">

                            <h2><?php echo "My Plugin $type"; ?></h2>
                            <p><?php echo $admin_notice->message; ?></p>

                        </div><?php
                    }
                }
            }
        }

        public function error( $message, $dismiss_option = false ) {
            $this->notice( 'error', $message, $dismiss_option );
        }

        public function warning( $message, $dismiss_option = false ) {
            $this->notice( 'warning', $message, $dismiss_option );
        }

        public function success( $message, $dismiss_option = false ) {
            $this->notice( 'success', $message, $dismiss_option );
        }

        public function info( $message, $dismiss_option = false ) {
            $this->notice( 'info', $message, $dismiss_option );
        }

        private function notice( $type, $message, $dismiss_option ) {
            $notice = new stdClass();
            $notice->message = $message;
            $notice->dismiss_option = $dismiss_option;

            $this->admin_notices->{$type}[] = $notice;
        }

	public static function error_handler( $errno, $errstr, $errfile, $errline, $errcontext ) {
		if ( ! ( error_reporting() & $errno ) ) {
			// This error code is not included in error_reporting
			return;
		}

		$message = "errstr: $errstr, errfile: $errfile, errline: $errline, PHP: " . PHP_VERSION . " OS: " . PHP_OS;

		$self = self::get_instance();

		switch ($errno) {
			case E_USER_ERROR:
				$self->error( $message );
				break;

			case E_USER_WARNING:
				$self->warning( $message );
				break;

			case E_USER_NOTICE:
			default:
				$self->notice( $message );
				break;
		}

		// write to wp-content/debug.log if logging enabled
		error_log( $message );

		// Don't execute PHP internal error handler
		return true;
	}
    }
}

MyPlugin_Admin_Notices::get_instance();

Thanks for reading

Please comment on what you liked or didn’t like in my code. What would you have done differently? Can you spot any bugs?

Until next time. Dismissed!

The post 🗨 Dismissible notices that persist when refreshing the WordPress admin screens appeared first on Alexandros Georgiou.

Digital Ocean backup feature

Perhaps one of the reasons Digital Ocean is currently such a popular VPS provider is its low-price affordable plans. Its $5/month plan makes perfect sense for small, low-traffic sites, especially if you bundle together a bunch of them on the same server.

Digital Ocean lets you take full weekly backups of your server for a modest price:

Digital Ocean can help you to weekly backup WordPress or any other type of sites at the server level.

These are backups of the entire system that you can later restore.

You can also take snapshots of your VPS, but you must first shutdown your server. This makes sense if you have setup a large system with replication and load balancers, but not as much in the low-cost setup where one small droplet serves a number of sites. Additionally, weekly backups seems to me as not enough granularity. Especially if your sites include e-shops or other sites where users frequently perform transactions, you’ll want to have frequent backups, perhaps daily.

Do it yourself

Fortunately, with only a few lines of code, you can roll your own backup system that will perform a full WordPress database backup in any way you like. Of course you can read on even if you have your server on another VPS service, or if you want to backup anything that uses a MySQL database, not just a WordPress site.

I opted not to go for any online storage solutions. The method I present here is what I chose to do based on my requirement of a low cost, fully custom solution that I can tweak any way I like. It requires a second machine where the backups will be kept. This machine lives at home and can be any old piece of hardware that’s lying around as long as it can connect to the internet.

The plan is to have the backup machine tell the VPS at regular intervals to take backups of the WordPress databases, then download these backups and store them by date/time. We will achieve this using cron, mysqldump, and rcp.

Set up passwordless remote access

This is the first thing you need to do. I will not go into detail because there’s a ton of articles on this (and really, you should have already done this). Here’s the official guide. The article says it’s for Ubuntu servers but the same process applies to Debian and friends.

Long story short:

1. Go to your local machine, and do

   ssh-keygen

   to generate a key pair if you don’t already have one.

2. Copy your public key to the droplet with

   ssh-copy-id user@droplet

   replacing user and droplet as needed.

Set up a “backup” user

Not strictly necessary, but for extra security it would be a good idea to not use the master database password that WordPress uses to create your WordPress backups. You can setup a read-only user on your MySQL database that has read access only to the databases you want to backup. Here’s an example of what to type into the MySQL command line interface. (You can also do this via phpmysql if you have it installed and configured.)

First, connect to your droplet with ssh

ssh user@droplet

where user is your actual user name and droplet is your server’s IP address.

Make sure the MySQL CLI is installed. We’ll also need mysqldump which is included in the same package. So, do this:

sudo apt-get install mysql-client

Once the package is installed, fire up the CLI with:

mysql -u root -p

On the next line you will be asked for the MySQL root password. (This is done because it’s not secure to type passwords on the shell’s command line.)

Once you’re in, you should be seeing the mysql> prompt. First, create a user and give it a password. I called my backup user wp_bu:

CREATE USER 'wp_bu'@'localhost' IDENTIFIED BY 'PASSWORD';

Pro tip: For maximum security, don’t use ‘PASSWORD’ as your password. This database user will have read access to all the data on all your websites. Choose a strong password, like you did with the root DB password and WordPress passwords.

Then you will need to choose which databases the user can read. If you’re not sure which databases you have, type this:

show databases;

Ignore the mysql database and other metadata such as information_schema or performace_schema. The other databases listed should correspond to all your sites. Let’s say you want to be able to backup the database with the name wordpress_db. Type this in:

GRANT SELECT, LOCK TABLES ON wordpress_db.* TO 'wp_bu'@'localhost';

Select and lock tables are the minimum access rights that you need to dump a database to disk. Repeat this line for every database you need to backup. When finished exit the CLI:

exit

The cron job

We’re now ready to setup a cron that will create the backups and copy them somewhere safe, hopefully. I assume you have a low-power machine somewhere in your house that you already leave on 24/7. This would typically be your torrent box, media center, bitcoin wallet, NAS, git upstream repo, trac server, etc. It will now also be the backup server for your sites.

Log in to your backup machine and do a crontab -e to edit your crontab. We’ll need to do three things:

1. Create the backup
2. Copy the backup
3. Delete the backup

Here’s an example of how to do this every day at 3 a.m. for a database named wordpress_db:

Create the DB backup

This is the most important part of our custom backup solution:

0 3 * * * ssh -t user@droplet "nice -n 19 mysqldump -u wp_bu -pPASSWORD wordpress_db |gzip -9 >/home/user/backups/wordpress_db-`date --rfc-3339=date`.sql.gz"

This crontab entry says that at 3 a.m. every day, your local machine is to use ssh to execute the command in double quotes as the user “user” on your server, where “droplet” is your server’s IP. The command itself uses mysqldump to connect to the local database with the wp_bu DB user we created earlier, and dumps the wordpress_db database to a gzipped file. The file name contains given the current date. This whole process is run with the nice -n 19 prefix, to make sure that the process is not given priority over our webserver.

Create the files backup

I’ll allow two minutes which should be plenty of time for my database to be dumped to file, but if you have a really large database, check to make sure

Now we want to also take a snapshot of the file contents of the website. Assuming that your WordPress install is at /var/www/wordpress:

2 3 * * * ssh -t user@droplet "nice -n 19 zip -9r backups/wp-`/bin/date --rfc-3339=date`.zip /var/www/wordpress/wp-content/* "

Copy the two backup files

After a few more minutes, I’ll use rcp to pull the files from the server.

10 3 * * * rcp user@droplet:/home/user/backups/* /path/to/droplet/backups/

This cron entry will again use the passwordless access that we have setup to copy the file to your local path.

Deleting the backup

It is a very very bad idea to keep backups on the same server, not only because you’re filling up your precious VPS space, but also for security reasons. Let’s wait another minute or so for rcp to finish (your mileage may vary), and then we’ll shred the files:

20 3 * * * ssh -t user@droplet "shred -u /home/user/backups/*"

This last cron entry will keep our backups directory clean on the server. You could just use rm to delete the files, but that’s way too non-paranoid for my tastes. (Also, those are rented SSDs, so no need to worry too much about wearing them out.)

Recovering

If something goes horribly wrong, you can import the latest .sql.gz file using phpmyadmin or simply using the mysql CLI. And just unzip the .zip file into a new wp-content dir. Make sure the files are owned by www-data, or whatever your server runs as, and you should be good to go.

In fact I recommend that you test restoring the backup on a local machine before something goes wrong. Really. Go test it now!

Lean backups

You’ll notice that these backups are not incremental. Assuming you’re using this backup method on small sites, the backup files shouldn’t get too large. But in any case you might want to make sure that your WordPress databases are not full of useless stuff. There are plugins out there that help you clean up databases from old edit revisions which take up space, as well as other useless data. I use wp-optimize every now and then. This also helps save space on your VPS.

Shameless referral link plug

If by any chance this article has convinced you to sign up to Digital Ocean (and why not, it’s a great service), please use my referral link https://m.do.co/c/44d4d2184573. You’ll instantly get $10 credit and if you keep using it I might get something out of it too. Thanks!

The post 🖴 Poor man’s guide to backup WordPress droplets appeared first on Alexandros Georgiou.