This repository is a boilerplate with which you can install Craft 3 locally and on Heroku as well. It has some Plugins already preinstalled, so you don't have to take care of the basics.
Click this button and directly deploy this 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:
Fill out all details and you are good to go!
$ git clone email@example.com:edenspiekermann/craft-heroku-boilerplate.git
$ cd craft-heroku-boilerplate $ rm -rf .git $ git init $ git add . $ git commit -m '🎈 project start 🎈' $ git remote add origin YOUR-REMOTE-PROJECT-URL $ git push --set-upstream origin master
Make sure you create an empty git repository (no
README.md or similar)*
.envfile in the root of your project
.env.example. These are all the details Craft needs for installation.
$ composer install
webthe root path you project
I would recommend using php with homebrew.
Install a specific php version with brew. For example:
brew install firstname.lastname@example.org. Like this you will be also able to install packages with PECL. To switch between PHP Versions, a very nice helper is the php switcher which is described here. Jump to the section: "PHP Switcher Script" and instsall it.
If you encounter an issue during the install process with pkg-config, install it with homebrew:
brew install pkg-config.
Now you can install imagemagick with PECL as well:
pecl install imagick, which is the recommended way to have it native with your php version.
This step is optional. If you want to deploy the project to Heroku then read on. If you only want to work locally, skip the section and jump to Start working with the project.
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 go there and replace the
"repository" URL with your repository URL. Push the changed
app.json and go to the Heroku deploy URL:
You will see a Heroku page for creating a new instance. 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 chose 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 had too much database traffic. This means, that you can not access the website anymore (Error 500 on both, local environment and Heroku as well) 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.
nvm use(read more)
yarn watchfrom the Terminal. This will start a webserver and proxy port :8888 (MAMP) to :3000 (webpack)
localhost:3000and enjoy hot reloading
All bundled files will live in the
web folder. I would recommend to not change the name of the folder.
If you feel like changing it, please read the Docs and don't forget to change the folder path after the bootscript in the
Procfile as wella s in the webpack files.
You can safely skip that part if you are not interested in CSS and JS guidelines.
postinstalltask is mainly for Heroku, after the installing the dependencies
yarn run lint:js
yarn run lint:styles
yarn run lint:js:fix. This will fix for example double quote to single.
precommitis the default task which runs before commiting. If this task fails, you can not commit
watchruns the webserver on
localhost:3000and has a hot reload on JS and SCSS files
buildbundles all JS and SCSS files and minifies the. Output path is the main Craft folder,
All webpack settings for development are in the
webpack.dev.config.js. There is no minification/uglify of the code.
All webpack settings for production are in the
webpack.prod.config.js. A minified JS and CSS file will be generated.
|--config ⭐ // Here are the basic configs for CraftCMS ([read more here](https://craftcms.com/docs/folder-structure)) |--modules // Holds any [Yii modules](https://www.yiiframework.com/doc/guide/2.0/en/structure-modules) your site might be using. |--src ⭐ // Asset folder for styling and scripting | |--js // All the .js files | |--scss // All the .scss files |--storage // This is where Craft stores a bunch of files that get dynamically saved during use.[read more here](https://docs.craftcms.com/v3/directory-structure.html) | |--logs // Stores Craft’s logs and PHP error logs. | |--rebrand // Stores the custom Login Page Logo and Site Icon files, if you’ve uploaded them. | |--runtime // Pretty much everything in here is there for caching and logging purposes. Nothing that Craft couldn’t live without, if the folder happened to get deleted. |--templates ⭐ // CraftCMS templates |--vendor // CraftCMS plugin folder |--web ⭐ // All files for production will go here (js, css, fonts, ...)
All folder you will most likly have to touch are marked with ⭐
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 you
.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 diretory of the server.
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).
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.
Assets in this volume have public URLs
@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)