Skip to main content

Self-host with Terraform

This page provides instructions to install MFE Orchestrator Hub using Terraform with Docker infrastructure as code.

Prerequisites​

Before you begin, ensure you have the following installed:

  • Terraform (v1.0 or higher)
  • Docker running on your machine
  • Git to clone the repository

Installation Steps​

1. Clone the Repository​

First, clone the MFE Orchestrator repository and navigate to the Terraform directory:

git clone https://github.com/mfe-orchestrator/mfe-orchestrator.git
cd mfe-orchestrator/terraform

2. Initialize Terraform​

Initialize Terraform to download the required providers:

terraform init

This will download the Docker provider (kreuzwerker/docker v3.6.1) and initialize the backend.

3. Review the Planned Changes And Apply​

Before applying, review what Terraform will create:

terraform plan

This shows all resources that will be created, including:

  • Docker networks
  • Docker containers
  • Docker images

There are no docker_volume resources: each container gets a host bind mount under ${path.root}/volumes/ — volumes/mongodb, volumes/redis and volumes/mfe-orchestrator for the uploaded microfrontends. The directories are created next to the root module, so the state of the installation lives in your working copy and is deleted with it.

Apply the Terraform configuration to deploy the infrastructure:

terraform apply

Type yes when prompted to confirm the deployment.

tip

The apply process will create all necessary Docker resources to run MFE Orchestrator locally.

4. Verify the Deployment​

After successful deployment, verify that containers are running:

docker ps

You should see the MFE Orchestrator containers up and running.

Accessing the Application​

Once deployed, you can access the application at http://localhost:8080.

An installation with no users answers with the Initial Setup screen rather than a login form. Read The first startup before you fill it in: it is public and ungated, so whoever reaches it first owns the installation, and the project name you type becomes a permanent slug.

Pinned images​

The module names released image tags rather than floating ones, so a terraform apply run today and one run in three months bring up the same stack:

ContainerImage
MFE Orchestratorlory1990/mfe-orchestrator:4.0.0
MongoDBmongo:8-noble
Redisredis:8.0.2-alpine

Upgrading is deliberate: change the tag in terraform/modules/microfronted-orchestrator-hub.tf and apply again.

Before you call it production​

The module is a local development stack, and two of its defaults are unsafe anywhere else:

  • MongoDB credentials are hardcoded. terraform/modules/mongo.tf sets root / example, and the orchestrator's NOSQL_DATABASE_URL names the same pair. Change both, together.
  • No JWT_SECRET is set. The module passes none, so the backend signs its tokens with the built-in default key — which means anybody who knows it can forge a token for the installation. Add JWT_SECRET=<a random value> to the env list in terraform/modules/microfronted-orchestrator-hub.tf, and a SECRETS_ENCRYPTION_KEY beside it if the installation will hold storage credentials or repository tokens.

Docker Compose warns about the same two defaults; the reasoning is there.

Container Variables​

For a complete list of environment variables you can configure, please refer to the Environment Variables page.