According to WordPress.org, 29% of the web is currently running using WordPress. The Trump White House is also using WordPress to empower their site. However, setting up WordPress to run may have a different experience in a different environment.
Some users will prefer to install WordPress in a shared-hosting environment. (By the way, according to their requirements, it may differ). Another type of web developers may consider hosting their WordPress site on the more expensive environment such as Virtual Private Server or Dedicated Server. In this cases, I’m writing about hosting WordPress on Heroku which provide Platform-As-A-Service (PaaS).
If you are familiar with deploying WordPress on normal Shared Hosting environment, you may wonder what such great deal installing WordPress on Heroku?
Firstly, Heroku provide an environment which using the ephemeral filesystem. This means all of your files uploaded through the WordPress Dashboard will be gone whenever your dyno got restarted. Secondly, Heroku also applying the use of Composer heavily and we are going to benefit from it. Both issues will be discussed throughout this article.
The best part of Heroku is, it’s completely free for the newbies/developers to play around with the environment that comes with free dyno type.
1. Before we start..
My requirement is pretty simple which I want the ability to:
- Install themes/plugin from public Git-Based repository
- Install themes/plugin from private Git-Based repository
Actually, everything is ready for the original forked-repository. However, to make things more easy and straight-forward, I have put the settings that you will easily change. You may notice that the repository is the base for this blog too!
Note: We expect you to have some skills on configuring Windows Environment Variables, PHP Programming Languages, Composer (Dependency Manager) and Git version control systems.
2. Deploying WordPress on Heroku
You need to create an app on Heroku. They provide several ways to which is whether through Command Line Interface (CLI) or through their web interface. Creating an app is a straight-forward process and it’s super easy. By the way, in this article, you will be creating Heroku App using the already defined script.
You need to wait for a minute which depending on your speed of your internet connection. Usually, it takes less than 10 minutes to complete both commands. Be sure to change my-app-name to your preferred name.
Note: If you are running Microsoft Windows, you are mandatory to use git clone from the command line because of symlink issue.
Note: If you are running Microsoft Windows with a Composer-Installed environment, you need to unregister your composer at System Environment Path temporarily during this install. This because symlink doesn’t work properly on Microsoft Windows-Based system.
Note: If you are running Microsoft Windows released prior to a version released on 2017 (Build 16299 a.k.a. Fall Creator Update), you need to install cURL to support the composer self-install procedure since there is no cURL bundled prior to and this version. You may refer to this instruction to proceed.
Note: If you are getting “Make an initial SSH connection to heroku.com to add it to known_hosts” message, execute “ssh heroku.com” may solve the issues.
Under the hood:
While you are running executing init.sh file, the Shell Script is doing this action:
- Create Heroku App.
- Installing add-ons: ClearDB, SendGrid, New Relic and RedisCache. (Don’t worry. Everything installed is on the free version. However, if your account is not verified yet with your Credit/Debit Cards, it may result in error due to requirement for ClearDB).
- Setting up required environment variables: (You may change later based on your needs):
- All WP Salts
- Running composer update (installing all required dependency).
- Saving changes specifically for composer.lock and commit.
- Push to Heroku App.
- Done. You may visit your app URL to complete installing WordPress.
Installing WordPress Themes & Plugins
Normal WordPress installation allows you to install themes & plugins on the WordPress Dashboard. However, because of an ephemeral filesystem, you are prohibited from doing so while hosting WordPress on Heroku.
If you are interested enough on using PHP Dependency Manager (Composer), you may notice that everything is configured through the Composer, including WordPress itself, Themes, & Plugins. Without going further, let’s go through installing Themes & Plugins.
- Due to the nature of Composer, every component that needs to be used must defined as a Composer package (or specifically as WordPress Plugin/Themes in composer.json file). This has may have not been done by many third-party WordPress Developers. However, you are in luck because someone has done it for you. To install Themes & Plugins that hosted on WordPress Repository you need to refer to WordPress Packagist.
- If you’re a developer that needs to use third-party themes/plugins that not hosted on WordPress Repository (but hosted in somewhere else like GitHub/GitLab/BitBucket/etc), you may do so. Simply by declaring the repository you want to import in repositories block in a composer.json file you will include the package in the repository ready to be used. This is an example of importing repository of Batcache.
- There is also some other type of repositories you can add. This feature is not limited Version Control System (VCS) based only! Here is the list of available type: (Tips: if you want to point to zip file, you need to declare the repository as package)
- You may also install themes & plugins even if the package is not hosted on somewhere else by simply copy into the public/wp-content/plugins or public/wp-content/themes.
Note on themes & plugins hosted on VCS-based: You may need to create a tag (version release) on your repository or Composer may skip your package.
Note on themes & plugins hosted on VCS-based: You need to create a composer.json file the root path of your repository and declare the all required information before tagging a version. composer init may guide you step by step to create the file or you can write it manually as well (example).
Note on themes & plugins hosted on VCS-based: You may need to fork and add your own composer.json file if the repository has no composer.json file and you have no privilege to add the file.
Note on themes & plugins hosted on VCS-based: If you are importing a private repository, you may need to use SSH URL instead of normal HTTPS URL and generate Access Token your remote Git. You also need to declare the token in auth.json file (should be in the same directory with composer.json. Refer to the example below). Be extra caution, you need to make your repository private once you commit your token to a remote repository or you need to revoke authorization immediately.
Note: It’s beneficial for you to read through this article for remote Git account that has 2-Factor Authentication enabled.
Making things done through WordPress Command Line Interface (WP-CLI) is a cool thing. The repository heroku-wp repository that you use has included WP-CLI. So you can use that feature straight away. However, please be noted that you personal working directory must be inside folder support (pwd: /support) to be able to use it.
or, you need to specify the installation path to /public.built.
Setting up Amazon S3 storage
Due to Heroku ephemeral filesystem, you might need Amazon S3 services in order to enable WordPress Media Library upload feature working as intended. Without setting up Amazon S3 storage, your uploaded files will be gone once the dyno gets restarted. If you don’t plan to use WordPress Media Library feature at all, you may consider disabling the WordPress Media Upload which will be discussed in the later section.
You need to run this command or you can set via Heroku web interface. You may refer to Repository readme for more explanation on this matter.
Note: At this point of writing (WordPress 4.9.2), the Amazon S3 integration with WordPress may have an issue with deleting files in Amazon S3 after deleting on WordPress Media Library.
Setting up SendGrid transactional email
SendGrid is available on your Heroku App since it’s created. You need to get the API Key and set in your WordPress Sendgrid Settings.
Disabling WordPress Media Upload
To disable WordPress Media Upload, you can install the plugin (make sure you activate it after installation).
Add the following in your composer.json
Note: Every time you update composer.json file, you required to execute composer update -vvv to update composer.lock file.
You may refer to WordPress Releases page on GitHub to check for a latest version number.
After that, you need to edit composer.json file and run composer update -vvv to update composer.lock file.
Setting Up WP-CLI in Microsoft Windows CMD
To integrate WP-CLI in Windows Command Prompt, you need to download the phar file at wp-cli.org. We recommend you to put the wp-cli.phar file to the same path with php.exe is located as it will cut additional step to set the environment path.
Now, every time you want to use wp-cli, you need to call wp-cli.phar. It seems not very good because it’s too long. Making it shorter should be great. There is always have some ways to overcome this and here how we fix the issues.
- Create new file on the same working-directory with name: wp
- Paste the code below into that file we just created.
Now you have wp installed locally on your Windows machine and you can call both wp or wp-cli.phar to execute WP-CLI.
P/s, if you are running on Linux environment, I would like to recommend you to read this article to install the wp-cli as a local user and not as a global.
Setting Up cURL in Microsoft Windows CMD
At the point of writing, Microsoft has announced for the insider preview that they will include the cURL module to the Command Prompt. However, if you are using the previous version of windows (Windows 10 Fall Creator Update and before), you need to install cURL by yourself. You may refer to Oracle website for more information.
This article is made possible by this reference: