Typical WordPress ACF Project Setup

This is a typical WordPress / Advanced Custom Fields Setup that we use for our WordPress projects. It’s a clean, simple but low-level approach, and I am very likely to automate most of it using ansible anytime soon.

WordPress Project

Access to Stage and Production Servers

  • Server names are www. and stage. plus the main domain
  • All servers are accessible through SSH keys. Ask Mario at mario@what.digital if you need one.
  • Access to servers is SSH / SFTP (key-based) only: sftp|ssh -i ./example.pem admin@stage.example.com
  • Username is always admin unless stated otherwise

Initial Deployment

  1. Set up the LAMPW stack according to this blog post
  2. Log into the system with SSH
  3. Generate a Github deploy key with ssh-keygen -t rsa -b 4096 -C "your_email@example.com"
  4. cat the public key in ~/.ssh and copy & paste it into the github’s repository’s settings -> deploy keys as read-only key. Give a speaking name (i.e. domain.com stage)
  5. Create a directory outside web root (preferably /var/git/) and git clone ssh/https repo url into it.
  6. Go to the theme folder and do a git submodule update --init --recursive
  7. in the theme folder do php composer.phar install
  8. Rename the example-.env file to .env
  9. Create a symlink (ln -s /absolute/path/to/origin /absolute/path/to/dest) for each theme / plugin in the repository to the according WP folders (themes / plugins)
  10. if the server doesn’t have npm: https://gist.github.com/isaacs/579814
  11. go to the tools folder in the wp theme folder and run npm install and then ./npm_modules/gulp/bin/gulp.js styles to translate SASS into CSS


  1. Go to /var/git
  2. git pull
  3. If you changed ACF fields, then you have to go to WP Admin web inteface at /wp-admin then Custom Fields then Syncable Fields and sync all the syncable field groups.
  4. go to the tools folder and run ./npm_modules/gulp/bin/gulp.js styles to translate SASS into CSS

* Never change the branch on stage or production servers.
* Never change code on the stage or production servers directly
* Never change the ACF field setup on the stage or production servers directly
* The master branch is read-only – You cannot deploy to production. Please create a Pull Request into master and follow the workflow as described below.

Deployment Workflow

  1. Client submits change request
  2. what.digital creates a technical brief including ETA
  3. Developer creates a new feature / change request branch (set speaking branch name!)
  4. Developer creates a PR from his feature / change request branch into stage branch
  5. what.digital accepts the PR
  6. Developer deploys to stage
  7. what.digital tests on stage and creates a PR from stage into master
  8. Mario at mario@what.digital accepts the PR and deploys to master

Database and Media Import / Export


sudo mysqldump -p db-name > db-name.sql
sudo tar -cvzf uploads.tar.gz /var/www/wordpress/wp-content/uploads

Move these files to another system using SFTP

sftp -i cert-name.pem admin@domain.com
get db-name.sql uploads.tar.gz

Import this data on the target system

sudo mysql -u root -p db-name < db-name.sql
sudo tar -zxvf uploads.tar.gz
sudo mv uploads /var/www/wordpress/wp-content/
sudo chown www-data:www-data -R /var/www/wordpress/

Then go to domain.com/phpmyadmin and change the entries siteurl and home in the table wp-options to the domain name.


  1. Check whether a page named Frontpage got created
  2. If necessary set it as Front Page in the WP settings
  3. Start adding content to the page.

Local Development

Initial Setup for Linux / Mac OS X

  • On Mac OS X I recommend using MAMP which simplifies the setup significantly
  • Then just wget https://wordpress.org/latest.tar.gz, unzip into the web root of MAMP
  • Follow the steps in ‘Initial Deployment’

Note: Windows as a development platform is not supported.


  • Set PRODUCTION to false in the .env so you can see the ACF sidebar menu item in WP admin
  • spin up compass watch in the theme directory to create css from sass
  • in your ~/.profile set up an alias like this for easy SSH: alias ssh-example-domain-stage="ssh -i /absolute/path/to/your/.ssh/example.pem admin@stage.exammple.com"