App configuration

This article provides and explains a very simple Geopoiesis configuration file that can get you started quickly. More concepts will be introduced in further articles, and the full API reference is available here.

Geopoiesis configuration is a static file, which you'll usually want to keep under source control and distribute as part of your application package. It uses HCL (HashiCorp Configuration Language), which is a configuration language built by HashiCorp. Terraform configuration itself is written using a flavor of this language, so you should hopefully feel immediately at home with it.

In the example configuration file below, you will see the following pattern being used a lot:

option {
environment {
variable = "VARIABLE_NAME"

This is one way of passing sensitive values to your Geopoiesis installation. It means that the value of the option will be set to the value of the VARIABLE_NAME environment variables. Please visit the Configuration API reference to see all available options.

Basic configuration file

# Backend represents all the backing services that are required
# for Geopoiesis to run. The minimum setup requires passing two
# environment variables you should have created when running the
# 'AWS setup' step a few articles earlier.
backend {
aws {
region = "us-east-1"
# This is the KMS key ID you have created. It is passed
# here as an environment variable.
kms_key_id {
environment {
variable = "AWS_KMS_KEY_ID"
# This is the exact AWS S3 bucket name you have created
# in the 'AWS setup' step.
s3_bucket {
environment {
variable = "AWS_S3_BUCKET"
# The name of the scope is immutable. If you ever change it,
# it is af if you created a brand new scope and abandoned the
# old one. Your history will be gone.
scope "hello-world" {
# Every scope needs a "domain", which is the scope of
# credentials produced by your identity provider. You can
# change this setting later, but make sure to update your
# OAuth redirect settings on the provider side.
# Also, note that the "domain" does not care about the port.
# It is not valid to run two scopes on the same domain but
# on two different ports.
domain = "localhost"
# The identity section sets up the credentials and settings
# for your authentication layer as well as permissions for
# the authorization layer.
identity {
# In this example we are setting up a GitHub provider,
# which at the time of this writing is the only available
# option. In the 'Identity setup' step you should have
# created all necessary dependencies and took note of the
# values you will be passing to the environment.
github {
client_id {
environment {
# Client ID, passed as GITHUB_CLIENT_ID environment
# variable.
variable = "GITHUB_CLIENT_ID"
client_secret {
environment {
# Client secret, passed as GITHUB_CLIENT_SECRET
# environment variable.
# The permissions section defines your authorization rules.
# You can whitelist individual user (through 'user' blocks)
# and teams (through 'team' blocks). For each of those
# blocks you can specify permission level. By default,
# 'write' is set to false.
permissions {
user "marcinwyszynski" {
write = true
# The source section defines where your definitions are stored,
# and how they can be accessed. At the time of this writing,
# only GitHub provider is supported.
source {
github {
# Name of the repository in organization/repository form.
repository = "geopoiesiscorp/infra"
# By default, the 'master' branch is considered the
# 'target' one - i.e. the one which defines your production
# environment. You can change this by setting 'branch'
# option to some other value - please see the API for
# details.
# ID of the GitHub App, which you will have created in the
# 'GitHub App setup' step.
app_id = "<replace>"
# ID of the GitHub App installation, which you will have
# created in the 'GitHub App setup' step.
installation_id = "<replace>"
app_key {
environment {
# GitHub App private key, which you will have created
# in the 'GitHub App setup' step. In this case, we are
# passing it as a base64-encoded GITHUB_ACCESS_TOKEN
# environment variable.
encoding = "base64"
webhook_secret {
environment {
# GitHub access token, which you will have created in
# the 'GitHub App setup' step, passed here as the
# GITHUB_WEBHOOK_SECRET environment variable.

Multiple configuration files

You will probably want to keep this file under source control, and pass it to your Docker image, which we will build in the next step. Note that even though one Geopoiesis installation uses a single configuration file, you can store multiple configuration files in one Docker image - for example one for each of your environments. Instead of passing the file name statically though the --config flag to the binary, you can specify it using the CONFIG_FILE environment variable. Please see the CLI reference article for all Geopoiesis command-line options.