Installation#
This tutorial describes how to install a Marble node on a server.
Prerequisites#
Docker#
Marble is deployed as a Docker application using the compose tool to manage various services that make up the application.
To install Docker on Unix/Linux either install Docker Engine (recommended) or Docker Desktop. If using an operating system other than Unix/Linux, you must use Docker Desktop.
Warning
We highly recommend installing Marble on a Unix/Linux machine, specifically Ubuntu 18.04+ if possible. All code is developed and tested on Ubuntu, and we cannot guarantee that the software will behave as expected on other operating systems.
Secure Access Over the Internet#
Marble is designed to be deployed as a web application on the internet. To make this possible, you must provide a domain name where your Marble node can be reached online. Marble also requires that all internet traffic to and from your Marble node be encrypted using an SSL certificate.
Specifically, you will need to ensure that your have the following:
Depending on your situation and where your server is located (on premises at your institution, a VM in a cloud environment, etc.) the details of how to acquire each of the above will vary.
However, here are some recommendations on where to look if you’ve never set up a publicly available web application like this before.
A fully qualified domain name (FQDN)#
You can usually purchase a domain name from one of the various domain name providers online. Search for “domain name provider” online. You may have to shop around a bit to find one that best fits your needs and budget.
If you are hosting your Marble node in a cloud environment, most cloud service providers also provide a free or discounted domain name with your purchase of a cloud based virtual machine.
A static public IP address for your server#
A static public IP address is required so that the domain name server will know where to forward internet traffic to.
If you are hosting your Marble node in a cloud based environment, follow the instructions from your cloud service provider on how to forward internet traffic to your virtual machine.
If you are installing Marble on premises at an institution, contact the institution’s IT department to ask how to acquire your public static IP for the purposes of setting up a web application.
Note
Most residential internet service plans only provide dynamic public IP addresses, which are not suitable for hosting a web application. You may be able to request a static IP address from your internet service provider (ISP) for a small fee depending on your ISP and/or geographical region.
An SSL certificate for the FQDN#
An SSL certificate will encrypt all internet traffic to and from your server allowing Marble to use the HTTPS protocol.
You may be able to acquire an SSL certificate from the same place that you purchased your domain name.
Otherwise, you can acquire a certificate from organizations like Let’s Encrypt.
We recommend using a tool like certbot to get and manage SSL certificates if you are managing them yourself.
Git#
The Marble source code is hosted on GitHub and a git client is highly recommended to download
and update the source code.
Your server may already have git installed. To check run the following command from the command line:
git --version
The output should be some information about the version of git currently installed on your machine.
If you do not have git installed, it can be installed from https://git-scm.com/downloads. Select your operating system
for information on how to install git.
Marble#
Marble is built using the Birdhouse software, which is a collection of web based climate science applications. Marble can be deployed using the birdhouse-deploy project.
Download the Birdhouse software#
git clone https://github.com/bird-house/birdhouse-deploy.git
This will download the Birdhouse source code to the current directory.
The most up-to-date version of the source code is on the master branch. We recommend always using this branch.
Command Line Interface (CLI)#
The command line interface (CLI) for interacting with the Birdhouse software can be found at bin/birdhouse.
This CLI provides utilities to manage the Birdhouse software like a docker compose project, display build information, and manage configuration settings.
For a full description of the CLI usage run it with the --help flag:
cd birdhouse-deploy
./bin/birdhouse --help
For convenience we recommend adding the birdhouse-deploy/bin/ directory to your PATH:
export PATH="$(readlink -f ./bin):$PATH"
# Now instead of running (from the root directory of this project):
./bin/birdhouse --help
# you can run (from anywhere):
birdhouse --help
Note
All tutorials in this section will assume that you have added the birdhouse executable to your PATH.
This means that all examples will be written as:
birdhouse ...
instead of
cd birdhouse-deploy
./bin/birdhouse ...
To ensure that your PATH variable always includes this directory in login shells:
echo "export PATH=$(readlink -f ./bin)"':$PATH' >> ~/.profile
Warning
It is no longer recommended to call scripts other than bin/birdhouse directly. In previous versions, we recommended
interacting with the platform by calling scripts (like birdhouse-compose.sh or read-configs.include.sh)
directly. These scripts have been left in place for backwards compatibility for now but may be moved or modified
in some future version. We recommend updating any external scripts to use the CLI as soon as possible.
Create the local environment file#
Your Marble deployment can be configured and customized by editing a local environment file. By default this file is located at birdhouse/env.local. To create this file:
cd birdhouse-deploy/birdhouse
touch env.local
An (incomplete) example of this file named env.local.example can be used as a starting point.
Warning
env.local.example contains a lot of default examples that must be updated. For this reason, we do not recommend
just copying env.local.example to env.local
Configure env.local#
The env.local file contains environment variables that are used when deploying the Marble software.
Instructions on which variables should be set in this file can be found in env.local.example. Please refer to this
file which will instruct you:
which variables must be set for all deployments
which variables can be modified to customize your deployment
how to enable additional components and which variables to set to customize these components
Deploying Marble#
The Marble stack can be started, stopped and inspected using the compose command to the birdhouse CLI which takes the same arguments as the docker compose commands.
This command will read the env.local configuration file, create a docker compose deployment file
based on this configuration and then execute any subcommands provided as if they were subcommands
to docker compose based on that file.
For example, to start the Marble stack:
birdhouse compose up --detach
This will call the docker compose up --detach
command which will start up all the docker containers required to run the Marble stack.
Similarly, to stop and bring down the stack use:
birdhouse compose down
which will call docker compose down internally.
Check that everything is working#
Once you have started the Marble stack with the birdhouse compose up --detach command, check that everything is
working properly by opening your webpage in a browser:
Navigate to the domain name that you set up
Ensure that the page loads as expected
Note that the page that loads should be the one set by the
PROXY_ROOT_LOCATIONvariable inenv.local
Ensure that the connection is secure (uses the https protocol with a valid certificate)
If not: ensure that your SSL certificate is up-to-date and that
BIRDHOUSE_SSL_CERTIFICATEvariable inenv.localis pointing to the correct file (see the birdhouse documentation for details)
Next Steps#
Now that you know the basics of how to configure and deploy the Marble stack you can select which optional components you would like to add to your stack:
Once you’ve done that, you will likely want to add your new node to the Marble network:
If you want to host data on your node:
And finally you’ll want to start adding users to your node:
Example installation steps#
Here is an example of how to install Marble on a server running Ubuntu 20.04, using mymarble.com as a FQDN, and where we get an SSL certificate using certbot. We assume that docker and git are already installed:
# Download source code
git clone https://github.com/bird-house/birdhouse-deploy.git
cd birdhouse-deploy/birdhouse
# Configure env.local
echo "export BIRDHOUSE_FQDN=mymarble.com" > env.local
echo "export BIRDHOUSE_DOC_URL='https://marbleclimate.com'" >> env.local
echo "export MAGPIE_SECRET=$(openssl rand -hex 32)" >> env.local
echo "export MAGPIE_ADMIN_USERNAME=admin" >> env.local
echo "export MAGPIE_ADMIN_PASSWORD=$(openssl rand -base64 12)" >> env.local
echo "export BIRDHOUSE_SUPPORT_EMAIL=info@mymarble.com" >> env.local
echo "export BIRDHOUSE_POSTGRES_USERNAME=postgres-birdhouse" >> env.local
echo "export BIRDHOUSE_POSTGRES_PASSWORD=$(openssl rand -base64 12)" >> env.local
echo "export POSTGRES_MAGPIE_USERNAME=postgres-magpie" >> env.local
echo "export POSTGRES_MAGPIE_PASSWORD=$(openssl rand -base64 12)" >> env.local
echo "export BIRDHOUSE_EXTRA_CONF_DIRS='...'" >> env.local # fill in the ... with the additional components you want to add
# Get an SSL certificate with certbot
sudo snap install --classic certbot
sudo ln -s /snap/bin/certbot /usr/bin/certbot
sudo certbot certonly --apache --domain mymarble.com # and follow any additional instructions
# Create a file that contains a combination of the fullchain.pem and the privkey.pem files
sudo cat /etc/letsencrypt/live/mymarble.com/fullchain.pem /etc/letsencrypt/live/mymarble.com/privkey.pem > cert.pem
echo "export BIRDHOUSE_SSL_CERTIFICATE=$(pwd)/cert.pem" >> env.local
# Start the server
birdhouse compose up -d