Deploying Metabase on Platform.sh

Contribute to the Platform.sh knowledge base, or check out our resources
Join our community ◦ Documentation ◦ Blog ◦ Report a bug ◦ Request a feature

About this project
- Features
Getting started
- Deploying
- Post-install
Customizations
About Platform.sh
Usage
Migrating
License
Contact
Resources
Contributors

About this project

This template builds Metabase for Platform.sh.

Metabase is a simple and powerful analytics tool which lets anyone learn and make decisions from their company’s data. The Metabase jar file is downloaded on the fly during the build hook based on the version provided in the application's configuration.

Features

Java 11
PostgreSQL 13
Automatic TLS certificates
Automatic Java heap size configuration
Automatic upstream updates via Source Operations

Getting started

If you are unfamiliar with Metabase, 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.

Deploying

The quickest method to deploy Metabase on Platform.sh is by clicking the button below. This will automatically create a new project and initialize the repository for you.

If you do not already have a Platform.sh account, you will be asked to fill out some basic information, after which you will be given a 30-day free trial to experiment with our platform.

Deploy manually

If you would instead to deploy this template from your command line, you can do so through the following steps.

Note:

If you do not already have a Platform.sh account, you will need to start a free trial before creating a new project.

Clone this repository:

git clone https://github.com/platformsh-templates/metabase

Install the Platform.sh CLI:

curl -sS https://platform.sh/cli/installer | php

Create a new project:
```
cd metabase && platform project:create
```

Set the project as a remote for the repository (prompt):

Set the new project Metabase as the remote for this repository? [Y/n]   Y

Once you have verified the project creation steps, you will receive some additional information about the project.

The Platform.sh Bot is activating your project

    ▄     ▄
    ▄█▄▄▄█▄
  ▄██▄███▄██▄
  █ █▀▀▀▀▀█ █
     ▀▀ ▀▀

The project is now ready!
<PROJECT ID>

Region: <PROJECT REGION>.platform.sh
Project ID: <PROJECT ID>
Project title: Metabase
URL: https://console.platform.sh/<USERNAME>/<PROJECT ID>
Git URL: <PROJECT ID>@git.<PROJECT REGION>.platform.sh:<PROJECT ID>.git

Setting the remote project for this repository to: Metabase (<PROJECT ID>)

Push to Platform.sh:
```
git push platform main
```

Post-install

After the first deployment, give the JVM a minute to finish completing it's initialization tasks (until it does, you will see a 502 error page.) which take only a minute or so. Run through the Metabase installer as normal. You will not be asked for database credentials, as those are already provided via the .environment that is sourced during the deploy hook. With the installer you will be able to create admin credentials and choose your language.

The installer will allow you to add databases. Configure the database you are trying to connect, or skip that step and Metabase will load an H2 Sample Dataset to start off with.

Customizations

Some more general explanation of why these files are necessary additions to replicate

The following files have been added in order to download Metabase during the build hook and to deploy the application on Platform.sh. If using this template as a reference for your own project, replicate the changes below.

Configuration

Every application you deploy on Platform.sh is built as a virtual cluster containing a set of containers which defines a particular environment. The default branch (master, main, etc.) is always deployed as your production environment, whereas any other branch can be deployed as a development environment. Within an environment there are three types of containers, each of which are managed by three required files that have been included in this repository:

The Router container (.platform/routes.yaml)

For each cluster/environment there will always be exactly one Router container, which is a single nginx process. It's configuration file .platform/routes.yaml defines how incoming requests map the the appropriate Application container, while providing basic caching of responses if so configured. The Router Container has no persistent storage.

Metabase

For Metabase, two routes have been defined. One upstream route directs requests directly to the Metabase application container at the www subdomain, which defined by the upstream value "app:http". Notice that the application container name app is matched in the name attribute in .platform.app.yaml.

'https://www.{default}/':
  type: upstream
  upstream: 'app:http'

'https://{default}/':
  type: redirect
  to: 'https://www.{default}/'

There is also a redirect route configured, which automatically redirects all request to the www subdomain upstream route.

A {default} placeholder is included on all defined routes. This placeholder will be replaced with the production domain name configured for your project's production branch, and will be substituted with a unique generated domain for each of your development environments based on the region, project ID, and branch name.

Service containers (.platform/services.yaml)

Each virtual cluster can have zero or more Service containers, but the file which configures them .platform/services.yaml is still required in your repository. Each top level key in that file will correspond to a separate Service container, with the kind of service determined by its type.

For Metabase's primary database, a single PostgreSQL service container has been added, identifiable by the service name db. Notice that in order for the application container to be granted access to this service it's necessary that a relationship is defined in .platform.app.yaml.

# .platform.app.yaml

relationships:
  database: 'db:postgresql'

With this relationship defined, the database will now be made accessible to the application on the internal network at database.internal with its credentials visible within the PLATFORM_RELATIONSHIPS environment variable, which is a base64-encoded JSON object. Along with a number of other Metabase-specific environment variables, service credentials are set within the .environment file, which is sourced in the application root when the environment starts as well as when logging into that environment over SSH. You will notice that this file leverages jq, a lightweight command-line JSON processor that comes pre-installed on all application containers.

Application containers (.platform.app.yaml)

There must always be one Application container in your cluster, but there may be more. It is from this file that you are able to define the container's runtime language and version, it's relationships to other containers, and how it is built and deployed.

Every project you deploy on Platform.sh exists on a writable file system at build time, but it will become read-only once it enters the deploy phase (see Builds and deploys) for more information. Because of this, any directories that require write access to the file system at runtime must be declared as mounts, and must include the disk attribute that defines the available disk space for the data in these directories.

Metabase

For Metabase, the temp and data directories are required in order to load the example dataset that comes with Metabase. Since the upstream jar file is unpacked during the start command, which includes writing a number of plugins to the filesystem, plugins will also be a mounted directory.

# The name of this application, which must be unique within a project.
name: app

# The type key specifies the language and version for your application.
type: java:11

Metabase's .platform.app.yaml file has a type specified such that Java 11 will be the container's primary runtime language. This container is accessible to the rest of the cluster by the name app, which you will notice is also the name used in defining Metabase's upstream route in .platform/routes.yaml.

The .platform.app.yaml file comes with many more features than are described here, so visit the Configure your application section of the documentation for more details.

Builds and deploys

Every time you push to a live branch (a git branch with an active environment attached to it) or activate an environment for a branch, there are two main processes that happen: Build and Deploy.

The build process looks through the configuration files in your repository and assembles the necessary containers.
The deploy process makes those containers live, replacing the previous versions, with virtually no interruption in service.

Upstream modifications

At this time, Platform.sh's Metabase template does not include any of the upstream code in this repository. The Metabase jar file is installed during the build hook according to the version defined in a metabase.version file.

About Platform.sh

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Donec eu est lacus. Integer magna est, pellentesque vitae lorem a, molestie pharetra felis. Quisque massa lorem, ullamcorper sed urna eu, gravida placerat ipsum. Quisque tempus ex at sapien finibus, consequat condimentum lorem vehicula.

Overview

Nulla ornare, nisl et vehicula convallis, felis arcu sagittis nibh, luctus faucibus nunc magna sed est. Proin blandit porta ligula. Ut euismod lectus eu tincidunt blandit. Nulla nec urna sit amet felis facilisis volutpat. Vestibulum sed lectus vulputate, dapibus leo sit amet, porta mi. Maecenas ac convallis eros, id efficitur quam. Nunc ornare tristique eleifend. Donec consectetur, eros in hendrerit cursus, velit erat pretium sem, ac viverra ligula odio nec odio. Vestibulum sit amet tellus tempor tellus faucibus laoreet sit amet in tortor.

Projects

Builds

Deploys

Environments

Usage

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

Logs

Once you have deployed to an active environment, you will be able to SSH into your application containers, which can be useful for many things including accessing logs. A temporary SSH token will be generated for you (once you have logged in through the browser) by running the command platform login. After that from your project's root, simply run the command

platform ssh

to gain access. Everything in your repository plus any artifacts of your build will exist here in /app. All logs are available in the subdirectory /var/log, and you can find more information about the available logs in the Development documentation.

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

Local development

Lando: Use the Platform.sh recommended local development tool

Docksal: Docker-based local development

DDEV: PHP local development

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

You are able to test out or build this template on your local machine by following the steps below:

Requirements

Platform.sh CLI
These steps open a tunnel to a PostgreSQL container on Platform.sh, so it is assumed that you have pushed to Platform.sh or clicked the Deploy on Platform.sh button above, and have followed the post-install instructions.

Steps

You are able to run the build.sh and start.sh scripts just as they're defined in .platform.app.yaml to run Metabase locally.

Download the project's current live committed version of Metabase (defined in the metabase.version file):

./scripts/build.sh

Then start the application for the downloaded jar file:

./scripts/start.sh

The script will automatically open a tunnel to the PostgreSQL instance on the current environment, so be sure to create a new one before making any changes.

Untethered: Using local services

Updating

This template downloads the Metabase jar file during the build hook using the build.sh script. The version downloaded is dependendent on the version listed in the metabase.version file in the repository.

./scripts/update.sh

An update.sh script has been included in this repository, which checks to see if a new version of Metabase is available, and if so updates the contents of metabase.version that will used on subsequent builds.

Scheduling automatic updates: automating upstream updates with source operations

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.

It is possible to schedule the updates described above using source operations, which are a set of commands that can be triggered to make changes to your project's code base.

A source operation has been defined for this template that is scheduled to run regularly with a cron job:

source:
  operations:
    update:
      command: !include
        type: string
        path: scripts/update.sh

The update.sh script - when a new version of Metabase has been released - will write the latest version to metabase.version. That change will be staged and committed in an isolated build container source operations run on, ultimately causing a full rebuild of the environment (but not using that latest version).

This command can be triggered at any time for any environment with the CLI command:

platform source-operation:run update

Ideally we would like:

For this update to occur automatically.
To only occur in an isolated environment, rather than to production.

The cron job defined in .platform.app.yaml does exactly this:

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

With this definition, the update source operation will check to see if a new version of Metabase is available every day at 1:00 am UTC, but only on the updates environment. If that environment does not exist on your project it will never run.

Migrating

Data

Moving from using Metabase Cloud to a Self hosted version means you also would need to migrate your data yourself. For the migration to happen, you'll need to obtain your database dump from metabase, you can do that by refering to this guide in the Metabase documentation.

Note:

It is advised you backup your database before proceeding with the dump.

When you have successfully obtained a dump of your data (MySQL, MariaDB or PostgreSQL) from Metabase, you'll need to populate the postgresql database service that this template uses. You can change the default database type of this template by altering the .platform/services.yaml file in the .platform folder if needed.

Next, you'll need to save your as database.sql. (Or any name, really, as long as it’s the same as you use below.)

Next, import the database into your Platform.sh site. The easiest way to do so is with the Platform.sh CLI by running the following command:

platform sql -e master < database.sql

The above command will connect to the database service on the master environment, through an SSH tunnel, and run the SQL import.

Adding data sources

If you need to add your previous data sources, all you need to do is to build and deploy your metabase site, visit the generated route to see the metabase site live.

Next thing is to follow this guide in the Metabase official documentation to learn how to add various data sources.

Note:

If you have a CSV file containing your data you'll need to upload the csv files to a database, then connect Metabase to the database.

Customizing Metabase

Adding a datasource

Adding a domain

Authentication

License

This template uses the Open Source edition of Metabase, which is licensed under the GNU Affero General Public License (AGPL).

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, you can join Platform.sh's public Slack channels and ping the @devrel_team with any questions.

Resources

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 better understand the 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!

Additional thanks to @rhubinak for creating the original template.

chadwcarlson/metabase