Deploying Directus on Platform.sh

Contribute to the Platform.sh knowledge base, or check out our resources

About Platform.sh       Join our community       Documentation       Blog      
Report a bug       Request a feature

        

If you're unfamiliar with Platform.sh, be sure to checkout the About section below.

This template demonstrates building Directus for Platform.sh. It includes a quickstart application configured to run with PostgreSQL. It is intended for you to use as a working starting point you can modify for your own needs.

Directus is an open-source platform that allows you to create and manage an API from data stored in a database.

Features

• Node.js 12
• PostgreSQL 12
• Redis 6.0
• Automatic TLS certificates
• npm-based build

Contents

• Getting started
• Customizations
• Usage
• Migrating
• License
• About Platform.sh
• Contact
• Resources
• Contributors

---

Getting started

If you are unfamiliar with Directus, with Platform.sh, or otherwise want to quickly deploy this template, start here. This template contains all of the files needed to deploy on Platform.sh, but you have a few options for doing so.

Whichever method you choose, be sure to make note of all of the information included in this README as it will be a great deal of help once your project has been deployed.

Contents:

• Deploying: Quickstart
• Deploying: Starting from an integration to a GitHub repository
• Post-install instructions

Deploying

Everything needed to deploy and develop a Directus application on Platform.sh is included in this project. Whether you choose to develop using a Platform.sh project as your primary remote (as in the quick start) or work on an integrated repository here on GitHub is up to you.

Quick start

The quickest method to deploy Directus on Platform.sh is by clicking the Deploy on Platform.sh button at the top of this page. This automatically creates a new project and initializes the repository for you. If you do not already have a Platform.sh account, you are asked to fill out some basic information, after which you are given a 30-day free trial to experiment with our platform.

Start working with the project

After you have deployed to a project, you can begin developing using Platform.sh as your primary remote repository. To clone the project, you have two options:

• Within the management console, go to the Production environment for your default branch. Open the dropdown labelled GIT. Copy and run the command locally to retrieve your repository.
• Install the Platform.sh CLI. With this tool, you can quickly authenticate with Platform.sh (with the command platform login) and view your available projects (with the command platform projects:list). Your project is listed with its unique PROJECT_ID. With that hash, you can quickly clone a local copy with the command platform get PROJECT_ID.

In both cases, you are now able to branch and push commits to Platform.sh. When you push a new branch to Platform.sh, it remains in an inactive state by default initially.

Install the Platform.sh CLI if you have not already done so and then run the command platform environment:activate BRANCH_NAME to begin the build and deploy phases in a new isolated environment. You can also activate this environment within the management console by visiting the Settings pane for the environment and editing the Status is Inactive section.

Starting from an integration to a GitHub repository

You also have the option of setting up a copy of this repository in your own namespace and then integrating it with Platform.sh as the continuous delivery component of its pipeline.

Setting up the integration

1. Create a copy of this template or click the Use this template button at the top of this page to create a fresh copy of this codebase in your own namespace.

2. Start your 30 day free trial on Platform.sh.

3. Create a new project on Platform.sh. After you create your account, you can create a new project. Select the Create from scratch option, give the project a name (like directus), and select a region where the application will live.

4. Save your PROJECT_ID. Every project on Platform.sh comes with a unique project ID that you need to set up your integration to GitHub. You can find this value in three places:

   • In the project URL in the management console. Your project has a unique location at https://console.platform.sh/<ORGANIZATION-NAME>/<PROJECT-ID>.
   • In the main project page in the console, click the More button (three vertical docs). The first option is the ID, which you can click to copy.
   • Using the Platform.sh CLI with the command platform project:list.

5. Generate a personal access token on your GitHub account. First consult our integrations documentation to ensure you grant the token the required scopes.

6. Install the Platform.sh CLI (if you have not already).

7. Authenticate using the CLI. You can do this quickly with the command platform login, which uses your current browser session to generate a local SSH key.

8. Enable the integration. Using the CLI, with the right PROJECT_ID from Platform.sh, your GITHUB_TOKEN, and your repository, run the following command:

   platform integration:add --type=github --project=PROJECT_ID --token=GITHUB_TOKEN --repository=GITHUB_USER/GITHUB_REPOSITORY

Developing on GitHub

Once you have integrated your project, Platform.sh validates and then mirrors your repository in the project you just created. It then builds and deploys the template for you. From this point forward, you can develop your application on GitHub.

With the default settings, your default branch is your production environment, while every pull request opened on the repository becomes an active development environment on Platform.sh.

Post-install instructions

This template does not require any additional configuration once deployed to start developing your Directus application. During the first deploy, however, an admin user is added to allow you to log in. Those credentials are set in the deploy hook in the .platform.app.yaml file:

hooks:
    deploy: |
        set -e
        # Installs the database and sets up the initial admin user. Only run on first deploy.
        if [ ! -f var/platformsh.installed ]; then
            echo 'Bootstrapping Directus on first deploy...'

            export PROJECT_NAME='Directus on Platform.sh'
            export ADMIN_EMAIL='admin@example.com'
            export ADMIN_PASSWORD='password'
            
            npx directus bootstrap

            # Create file that indicates first deploy and installation has been completed.
            touch var/platformsh.installed
        fi;

After you log in for the first time, be sure to update this password immediately.

Customizations

The following files and additions allow Directus to build and deploy on Platform.sh. They are placed on top of the basic Directus starter project (npm init directus project). If you are using this project as a reference for your own existing project, replicate the following changes in your code.

Contents:

• Changes to the codebase
• Platform.sh configuration

Changes to the codebase

• .gitignore: A .gitignore file has been added to the Directus starter project, which does not include one. Its contents prevent you from committing dependencies and sensitive information in your .env file and SQLite database.
• package.json: The argon2-rebuild script has been added, as recommended by Directus, so that the database can be initialized during directus bootstrap.
• .env.example: The npm init directus-project script generates a .env file based on your answers to a set of prompts (for example, which database driver you want to use). The file contains a set of environment variables for developing a Directus application. Platform.sh has added a .gitignore file to this repository that prevents .env from being committed, since including it is generally considered bad practice and a path for unintentionally committed secrets. A fairly similar .env.example file has been included. It contains many of the same environment variables, including those settings that enable you to develop locally over a tethered connection to Platform.sh services. For more details of how to use this file, read the Tethered local development instructions.

Platform.sh configuration

Platform.sh is able to build and deploy projects by detecting configuration in a few files, which have been added to the starter repository. For more details, view the comments in the individual files and the following linked documentation.

• .platform/routes.yaml: This file defines how requests are handled by a router container.
• .platform/services.yaml: This file defines which of Platform.sh's managed service containers are included alongside the template.
• .platform.app.yaml: This file defines how Directus is built and deployed within a single application container.
• .environment: This file provides Platform.sh-specific environment variable overrides of the generated default .env settings for Directus and PostgreSQL. It also sets an initial username and password for an admin user. On Platform.sh, a .env file is required to configure Directus but is not committed in this project. Rather, at build time Directus's example.env file (node_modules/directus/example.env) is renamed in its place with a set of standard defaults which are then overridden by .environment. Consult this file locally and then override with your own settings in .environment when appropriate.

Usage

Once you have deployed this template, there are a number of next steps you can take to interact with and customize the project.

Contents:

• Setting up local development
• Updating
• Development
• Logs

Setting up local development

There are a few options for developing locally with Directus and Platform.sh.

Tethered: Connect directly to your Platform.sh services over an SSH tunnel

This template has been set up to help you develop Directus locally by opening a tunnel to services running on a live Platform.sh environment. Because of this, there are a few requirements that need to first be met:

Requirements:

• A deployed Directus template
• The Platform.sh CLI installed on your machine
• A local copy of this template repository
• npx installed locally

Once you have met these requirements, follow these steps:

1. Create a development environment.

   git checkout -b updates
   git push origin updates

   You can push to the project directly if you have not integrated with GitHub (platform environment:activate updates). Otherwise, open a pull request for the branch you have just pushed to GitHub.

2. Tunnel to services

   Once the environment has successfully deployed, you can use the CLI to open a tunnel to start a tethered local development environment to your services. To open the tunnel, run the command:

   platform tunnel:open

   Note

   If working from an environment created from a pull request on GitHub, make sure to add an environment flag to the tunnel:open command (for example, platform tunnel:open -e pr-8).

   This provides the following output:

   SSH tunnel opened to database at: pgsql://main:main@127.0.0.1:30000/main
   SSH tunnel opened to redisratelimit at: redis://127.0.0.1:30001
   SSH tunnel opened to rediscache at: redis://127.0.0.1:30002
   
   List tunnels with: platform tunnels
   View tunnel details with: platform tunnel:info
   Close tunnels with: platform tunnel:close
   
   Save encoded tunnel details to the PLATFORM_RELATIONSHIPS variable using:
   export PLATFORM_RELATIONSHIPS="$(platform tunnel:info --encode)"

3. Mock environment variables

   In order to match the environment on Platform.sh, run the command suggested in the output to retrieve connection credentials for the services now tunneled locally.

   export PLATFORM_RELATIONSHIPS="$(platform tunnel:info --encode)"

   Note

   If working from an environment created from a pull request on GitHub, make sure to add an environment flag to the tunnel:info command (for example, export PLATFORM_RELATIONSHIPS="$(platform tunnel:info -e pr-8 --encode)").

   A .env.example file has also been included in the repository based on the one provided from Directus. Use that file to create a local, uncommitted .env file:

   cp .env.example .env

4. Start Directus

   With your environment set up, install your dependencies (npm install) and then run the Directus server locally:

   npx directus start

There are also some additional things to keep in mind when developing locally, specifically related to how data works on Platform.sh.

A note on data: Runtime write access and the Platform.sh data model

As you develop your Directus application, there are a few things to keep in mind that are specific to how Platform.sh handles data. Platform.sh abstracts much of the operations you would normally have to write and maintain yourself. Part of the assurance provided with the platform comes from treating infrastructure as code and therefore as an equal part of the build image that identifies the state of your application for a particular commit.

This is advantageous for a few reasons. First, it means that commits can be rolled back to a previous build image by running git revert on your changes. Second, it means that if you make a change to your site that does not affect the build itself, the build image can be reused when an environment is created (branching) or promoted (merging). Both of these remove any sort of worry that might come with merging into production or trying out a new feature quickly on a development environment.

Code and data work differently in this model. They are separate entities, with different inheritance rules. Code can always be inherited by a child branch/environment. Data (such as in a production database or a parent mounted directory) is also inherited -- giving you a true staging environment for any change made to your application in a development environment.

Merging changes things. Code can move upwards from a development environment to its parent, but data cannot. That means that any new endpoints created for Directus in a development environment do not get merged to production unless a database dump is explicitly uploaded to production. Only changes to code (like custom modules) make it to production. This makes up one half of our repeatable builds methodology.

The other half is that your application and its infrastructure generates a build image and that image only changes when the code changes. To ensure this approach is followed for Directus, there is no write access to the file system post-build. You cannot make changes to the file system at runtime. It's recommended instead that you make and commit those changes in your local development environment and then push them to an environment on Platform.sh.

Updating

This template is managed with npm, so to update to the latest version:

1. Create a new environment to test the changes.

   platform environment:branch update-directus

2. Retrieve updates with npm.

   npm update

3. Test these updates on Platform.sh.

   git commit -am "Update Directus." && git push origin update-directus

Scheduling automatic updates: Automating upstream updates with source operations

Requirements:

• Platform.sh CLI installed in your application container with a configured token environment variable

Note:

This section describes features only available to Elite and Enterprise customers. Compare the Platform.sh tiers on our pricing page or contact our sales team for more information.

The updates described above can be scheduled using source operations, which are a set of commands that can be triggered to make changes to your project's code base. For example, a very basic way of automating the updates described above might look like this in your .platform.app.yaml file:

source:
    operations:
        update_dependencies:
            command: |
                npm update
                git commit -am "Update Directus."

Once the operation has been defined, you can trigger it to make the commit on a non-production environment with the CLI (platform source-operation:run update_dependencies) or by defining a cron job that runs it periodically:

timezone: "Europe/Paris"
crons:
    update:
            spec: '0 3 * * *'
            cmd: |
                if [ "$PLATFORM_BRANCH" == "auto-updates" ]; then
                    platform environment:sync code data --no-wait --yes
                    platform source-operation:run update_dependencies
                fi 

With the above configuration, the operation checks for and applies updates on the auto-updates environment every day at 3 AM Paris time.

This is not the only way to implement scheduled updates with source operations -- it's only a basic example. This template has a more complicated implementation to keep it up-to-date. You can find another useful resource at our community site, where we go into much greater detail about how scheduled dependency updates might work for you.

Developing

Once you have deployed Directus and prepared your local development environment, you are now ready to develop your application. Directus provides an excellent getting started overview video that you can use to begin setting up your site.

Logs

Once you have deployed to an active environment, you can SSH into your application containers, which can be useful for many things including accessing logs. A temporary SSH token is generated for you (once you have logged in through the browser) by running the command platform login.

To gain access to the log, run this command from your project's root:

platform ssh

Everything in your repository plus any build artifacts exist here in /app. All logs are available in the subdirectory /var/log. You can read more information about the available logs.

You can also view application logs directly using the Platform.sh CLI command platform logs app.

Migrating

If you are trying to migrate your existing Directus application to Platform.sh, there are a few things you need to do:

Using different services: Platform.sh provides managed services so you can match your database

This template uses PostgreSQL as its primary database, but this is not the only database available for Directus.

1. Update the driver.

   Remove the current PostgreSQL driver library and add the one you are currently using. For example, with MariaDB run this command:

   npm uninstall pg && npm install mysql2/promise

2. Add the service.

   Find your service in our services documentation, including which supported version matches the minimum requirements outlined by Directus. Then replace the current configuration for PostgreSQL in services.yaml with the configuration for your service. An commented-out example for MariaDB has already been included in that file.

3. Update the relationship.

   An environment on Platform.sh describes a collection of containers. .platform.app.yaml describes how an application container should be built and deployed, while .platform/services.yaml describes which managed service containers should be included in the cluster. For them to communicate with each other, the application container must be given access through the definition of a relationship. Here is the current configuration of PostgreSQL:

   # From .platform.app.yaml
   relationships:
       database: "db:postgresql"
   
   # From .platform/services.yaml
   db:
       type: postgresql:12
       disk: 256

   db is the name attributed to the PostgreSQL container and is used again in the relationship definition database: "db:postgresql". When switching to another service, make sure to repeat the same pattern in this block. If you preserve the alias the application uses to query the database (database), you do not need to update any of the environment variable logic included in .environment when switching to another service. The endpoint postgresql is specific to the database you choose to use, so be sure to revisit the services documentation for the correct configuration.

Importing your database

When you have successfully obtained a dump of your data for Directus, you need to populate the production database service that this template uses. If necessary, you can change the default database type for this template by altering the .platform/services.yaml as described above first.

Import the database into your Platform.sh environment. The easiest way to do so is with the Platform.sh CLI by running the following command:

platform sql -e main < database.sql

The above command connects to the database service on the main environment, through an SSH tunnel, and runs the SQL import. Make sure to update the command to match the names of your database dump and your default branch on Platform.sh.

Importing your files

You first need to download your files from your current hosting environment. The easiest way is likely with rsync, but consult your current host’s documentation. This sections assumes that you have already downloaded all of your user files to a local directory.

The platform mount:upload command provides a straightforward way to upload an entire directory to your site at once. Under the hood, it uses an SSH tunnel and rsync.

Note:

There is also a platform mount:download command you can use to download files later.

Run the following from your local Git repository root (modifying the --source path if needed and setting <DEFAULT_BRANCH> to the name of your project's default branch). Note that rsync is picky about trailing slashes, so be sure to include those.

platform mount:upload -e <DEFAULT_BRANCH> --mount uploads --source ./backups/uploads

After following the above steps, your files and database are now loaded onto your Platform.sh production environment. When you make a new branch environment off of it, all of your data is fully cloned to that new environment so you can test with your complete dataset without impacting production.

License

This template uses the Open Source edition of Directus, which is licensed under the GNU General Public License v3.0.

Resources

• Directus
• Directus documentation
• Directus repository
• Node.js on Platform.sh

About Platform.sh

Platform.sh is a Platform-as-a-Service (PaaS) provider and a DevOps platform for deploying and managing your web applications. It attempts to simplify DevOps according to a level of abstraction that keeps your applications secure, your development unblocked, and your time focused on your sites rather than on operations and infrastructure.

Some of the key features of Platform.sh include:

Infrastructure-as-code: Your infrastructure is a dependency of your app

All of your services can be defined in the configuration files described above and committed to your repository. These files are committed so your infrastructure becomes another dependency of your application like any other and every branch is capable of inheriting the exact infrastructure used in production.

Development environments: Every pull request should get a real staging environment

Every project has a live production site, but the concept of branching your repository has been extended to the provisioning of staging and development infrastructure. Every branch can become an active, deployed environment that contains the same infrastructure as production until you explicitly change its configuration.

Each environment receives its own unique preview URL, automatically renewed Let's Encrypt certificates, and scoped access permissions and environment variables. Environments exist in isolation from production: they are exact copies with fresh containers that cannot affect the production site. During the branching process, a development environment also receives copies of all production data at the time of the branching. You are free to use that data for your tests and can resync to more current data at any time.

Reusable builds: Provision the infrastructure diff, Deploy on Friday

The build and deploy tasks defined in your configuration are committed and Platform.sh is capable of defining infrastructure provisioning requirements for a particular commit to the same differences that define the Git protocol. So a single commit is associated with a unique build image. If the build and deploy stages of your pipeline remain undefined between commits, that unique build image is reused on that second commit.

This makes branching to a new development environment on Platform.sh possible and also removes almost all concerns associated with merging a particular commit into production. When the merge is initiated, it isn't necessary to run through the build and deploy again and risk failure. The build image has already been created and defined on an identical development environment, so it can be reused on production.

Managed infrastructure: Focus on your application, not operations, infrastructure, or patch updates

Every service and runtime container can be specified down to the supported minor version using the type attribute, while security and patch updates are applied automatically in the background between deployments when they become available.

FleetOps: Extend Platform.sh-powered DevOps to hundreds of applications

The Platform.sh API extends past single projects. It is possible to define your own upstream template repositories that are used to initialize a fleet of websites. You can also define operations and activity notification scripts that can be used to fully manage hundreds of applications under the same logic and assurances of a single project.

You can see Platform.sh in action in the brief demo below.

Platform.sh.Introduction.Demo.mp4

For more information, check out our website and public documentation.

Contact

This template is maintained primarily by the Platform.sh Developer Relations team and they will be notified of all issues and pull requests you open here.

• Community: Share your question with the community or see if it's already been asked on our Community site.
• Slack: If you haven't done so already, join Platform.sh's public Slack channel and ping the @devrel_team with any questions.

Contributing

Help us keep top-notch templates!

Every one of our templates is open source and they're important resources for users trying to deploy to Platform.sh for the first time or to better understand how to best run software on our platform. They act as getting started guides, but also contain a number of helpful tips and best practices when working with certain languages and frameworks.

See something that's wrong with this template that needs to be fixed? Something in the documentation unclear or missing? Let us know!

How to contribute

Read the Contributing Guidelines
Report a bug
Submit a feature request
Open a pull request

Need help?

Ask the Platform.sh Community
Join us on Slack

Thanks to all of our amazing contributors!