To make sure we can seamlessly work in teams, we have a specific requirements for our hosting environment. Currently, our hosting solution of choice is Netlify and Heroku. Netlify is mostly for our static websites. Heroku is for almost all other projects. With Craft 3, which was released in April’18, it’s already much easier to install the CMS as a composer package and host it. But there were still some things we needed to take care of in order to host it on Heroku.
This is a guide on how to set up a Craft 3 project on Heroku.
The quick and dirty start
This button has been made for those who just want to have a fresh Craft 3 instance on Heroku. Click the button and directly deploy our public boilerplate repository to a new instance on your Heroku account.
After the install process, visit the URL of your app and add
/admin/install to it. For example:
Fill out all the details from the guide and you are good to go!
Start from scratch
Set up a new project
First we need to clone our Boilerplate Repo into a local folder:
Rename the folder and make it your project:
Now we need to remove the Github connection and connect the folder with your own Git repository.
Go and create a new and empty Git repository with your account. There must not be any
README.md file. After it is created, go with:
Deploy to Heroku
To make your repository work on Heroku, we first have to update the reference URL with your freshly created repository.
Heroku reads all the deploy details from the app.json file. So we need to replace the
"repository" URL with your repository
Push the changed
app.json to your GitHub repository and adjust the following link with your repository and branch:
After you adjusted the link, visit it in your browser. You will see a Heroku page for creating a new instance.
It will also install a free plan of a MariaDB and connect it with Craft. Please fill out all the details and don’t forget to choose the region. If you are in Europe, please use Europe and US if you are in the US or nearby. If you choose the wrong region, it could be that your website is slower than it could be.
If you have multiple Users, it is recommended, that you upgrade at least the database to a paid plan. It can happen, that the
max_connections of the free database plan is used up, when you have too much database traffic. This means, that you can not access the website anymore (Error 500) and you have to upgrade the database plan.
Depending on the traffic, you also may have to upgrade the Heroku servers to a paid plan.
Heroku Post install
After the deployment process is successful, go to your new created website and add
/admin/install to the URL. Craft will help you to make the setup complete.
Use it locally
To complete your development environment, you should make the project running on your local machine as well:
- Create a
.envfile in the root of your project
- Copy over all dummy content from
.env.example. These are all the details Craft needs for installation.
- Install all dependencies
- In Mamp, make
webthe root path you project
- Go to
- Follow the Craft install guide
Having troubles with PHP extensions?
If you have any issues with missing php extensions during
composer install command, you have to make sure the extension
ext-imagick are installed. For OSX, it is best to install
php (must be >7) with homebrew and
imagick with pecl (PHP extension manager):
Start working with the project
- Use the recommended node version with
- Install all dependencies with
- Start MAMP (make
webthe root path you project)
yarn watchfrom the Terminal. This will start a web-server and proxy port :8888 (MAMP) to :3000 (webpack)
- Go to
localhost:3000and enjoy hot reloading
- If you want to make the bundle production ready, do
Plugins which come with the project
Set up Cloudinary in Craft
- Go to your
Admin -> Settings -> Assets
- Create a new Volume
- Type in a name you like (f.e.
Assets in this volume have public URLs
- You can decide on your Base URL (f.e.
@webis the root of your website but you can also go with
@web/imagesif you want to have
http://yourwebsite.com/images/as your public image path)
- Volume Type must be
- Now fill in the Cloudinary credentials
- Go to the Assets and upload the first image
The Blitz Plugin is only for production. It is a intelligent static file caching for creating lightning-fast sites. If you enable this, your site will be very fast, but you will not see the debugger toolbar. So make sure to disable it in development from the admin panel.
If the page is still under construction, it is a good idea to password protect it. Therefore we use Gatekeeper.
If you want to develop locally, I can highly recommend you to use a local database, otherwise the website will be quite slow.
To change the database, head over to your
.env variable, change the value of
JAWSDB_MARIA_URL and restart the server.
Craft has its main folder not in the root directory (in this project it is the
web folder), so we need to do some adjustments on the Heroku web server settings. Heroku provides optional configurations in the Procfile.
In this project we need to start an Nginx as a web server and make
web the root directory of the server.
I would recommend to not change the name of the
If you feel like changing it, please read the Docs and don’t forget to change the folder path after the boot-script in the
This project is using MariaDB instead of MySQL. MariaDB is a complete drop-in-replacement for MySQL. If you need to migrate some datas, you should not have problems here. If you do, you can change the database connection at any time in the Heroku interface by replacing the
JAWSDB_MARIA_URL URL with your database URL (
settings --> config vars).