How to deploy a Gatsby project with our quickstart repository¶
The Gatsby Divio quickstart repository is a template that gives you the fastest possible way of launching a new Gatsby project on Divio.
It uses a completely standard Gatsby project as used in the Gatsby Hello World boilerplate.
The repository contains some additional files to take care of the Docker set-up.
Clone the repository¶
git clone email@example.com:divio/gatsby-divio-quickstart.git
Run the project locally¶
This section assumes that you have Docker and the Divio CLI installed. You also need an account on Divio, and your account needs your SSH public key. See How to set up the Divio local development environment if required.
Build the Docker image¶
Launch the local server¶
This starts up the container with the default
command in the
gatsby develop --port 80 --host 0.0.0.0
Try accessing the site at http://127.0.0.1:8000/.
If you comment out that line in
docker-compose.yml, it will start up with the command specified in the
You now have a working, running project ready for further development. All the commands you might normally execute
in development need to be run inside the Docker container - prefix them with
docker-compose run web.
Deployment to Divio¶
Create a new project on Divio¶
The first step is to create a project on the Divio Control Panel, with your application repository.
You have two ways of doing this:
New project, in which you will push your local Git code to Divio’s Git server
New project from Git repository (Beta), in which your Divio project will fetch the code from a Git host
In the Divio Control Panel, add a New project. Select the Build your own option.
Once the project has been created, copy the project’s Git URL from its Repository view. Add the project’s Git repository as a remote, for example:
git remote add divio firstname.lastname@example.org:my-divio-project.git
Commit and push your work.
If you’re using the
master branch, you will need to force push to overwrite the initial commits in a Divio
project with your own.
You can use
divio project commands such as
divio project dashboard to interact directly with the Divio
In the Divio Control Panel, add a New project from Git repository. Once you have supplied the Git repository URL, you will need to use the public key provided to create a Deploy Key on the repository.
Beta status limitations
Some limitations apply to the current version of this functionality. In order to import a repository, at the time of import:
you will need to enable write access on the repository’s deploy key
the repository will need a
Once imported, you can remove the write access and can delete the
master branch if you don’t need it.
You should also add a webhook, so that when new commits are pushed to the repository, it will send a signal to update the Divio Control Panel.
In the Environments view, configure each environment to use the appropriate branch.
Connect your local application to the cloud project¶
You can connect a local application to a Divio project on the cloud. This is very convenient, allowing you to interact with the cloud project from your command-line.
divio project configure
and provide the slug (this creates a new file in the project at
The cloud project has a slug, based on the name you gave it when you created it. Run
divio project list -g to get
your project’s slug.
You can also read the slug from the Control Panel:
You can now use commands such as:
divio project dashboard divio project pull db # also push divio project pull media # also push divio project deploy
See some usage examples.
Add database and media services¶
The new Divio application does not include any additional services. If your application requires a database or media store, they must be added manually using the Divio Control Panel as required. Use the Services menu to add the services your application needs.
Add release commands¶
If your application needs to perform operations each time it is deployed, for example start-up health tests or database migrations, these should be applied as release commands.
Add additional environment variables¶
Your application may require additional environment variables in production. Apply any enviroment variables using the Divio Control Panel or CLI.
Push local database/media content¶
If you have local database or media content, push them to the Test environment:
divio project push db divio project push media
Deploy the Test server¶
divio project deploy
(or use the Deploy button in the Control Panel).
Once deployed, your project will be accessible via the Test server URL shown in the Control Panel.
Customisation and further development¶
You have multiple options for customisation. For example, this application is not configured to use a database, but if you need to Gatsby makes several database options possible. Other customisation could include installing additional system-level packages, Gatsby plugins and so on.
You’ll need to change a few lines of configuration to achieve this across a few files. See the notes for each of:
Building on the host as an option¶
If you uncomment the:
# - ".:/app:rw"
entry in the
web:volumes section of
docker-compose.yml, the entire
/app directory will be overridden by the
project files from the host. This can be useful for development. However, you will now need to run the commands
gatsby build on the host as well in order to regenerate the files so that the container sees them.