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
- Getting started
- Customizations
- About Platform.sh
- Usage
- Migrating
- License
- Contact
- Resources
- Contributors
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.
- Java 11
- PostgreSQL 13
- Automatic TLS certificates
- Automatic Java heap size configuration
- Automatic upstream updates via Source Operations
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.
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
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.
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.
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:11Metabase'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.
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.
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.
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
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. Quisque posuere justo velit, vel luctus ipsum rutrum vel.
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
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. Quisque posuere justo velit, vel luctus ipsum rutrum vel.
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.
Builds
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. Quisque posuere justo velit, vel luctus ipsum rutrum vel.
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.
Deploys
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. Quisque posuere justo velit, vel luctus ipsum rutrum vel.
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.
Environments
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. Quisque posuere justo velit, vel luctus ipsum rutrum vel.
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.
Once you have deployed this template, there are a number of next steps you can take to interact with and customize the project.
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 sshto 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.
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.
Lando: Use the Platform.sh recommended local development tool
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. Quisque posuere justo velit, vel luctus ipsum rutrum vel.
Docksal: Docker-based local development
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. Quisque posuere justo velit, vel luctus ipsum rutrum vel.
DDEV: PHP local development
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. Quisque posuere justo velit, vel luctus ipsum rutrum vel.
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:
- 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.
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.shThen start the application for the downloaded jar file:
./scripts/start.shThe 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
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. Quisque posuere justo velit, vel luctus ipsum rutrum vel.
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.shAn 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.shThe 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 updateIdeally 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
fiWith 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.
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.sqlThe above command will connect to the database service on the master environment, through an SSH tunnel, and run the SQL import.
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.
Adding a datasource
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. Quisque posuere justo velit, vel luctus ipsum rutrum vel.
Adding a domain
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. Quisque posuere justo velit, vel luctus ipsum rutrum vel.
Authentication
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. Quisque posuere justo velit, vel luctus ipsum rutrum vel.
This template uses the Open Source edition of Metabase, which is licensed under the GNU Affero General Public License (AGPL).
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_teamwith any questions.
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!
Read the Contributing Guidelines
Report a bug
Submit a feature request
Open a pull request
Ask the Platform.sh Community
Join us on Slack
Additional thanks to @rhubinak for creating the original template.