Installation

Local Installation for Testing

Prerequisites

• Docker and Docker Compose installed
• Git (to clone the repository)
• Basic familiarity with command-line tools

Step 1: Download Simple-stack repository

git clone https://github.com/your-repo/simple-stack.git
cd simple-stack

Step 1.1: Prepare Environment Variables

Create a temporary admin account that will be used only for initial setup:

export TEMP_ADMIN_EMAIL="admin@example.com"
export TEMP_ADMIN_PASSWORD="ChangeMe123!"
export SIMPLE_STACK_UI_URL="http://ui-next:3000"
export NEXTAUTH_SECRET="<random-key>"
export UI_NEXT_PORT=3000

This temporary account allows you to log in and create a permanent admin user in the UI. You can delete it later.

Step 1.2: Prepare Your SSH Configuration

Create and maintain your SSH keypair and host access configuration in your home directory:

• SSH keys in ~/.ssh/
• SSH client configuration in ~/.ssh/config

Base configuration example:

Host *.project
   User ubuntu
   Port 22
   ServerAliveInterval 50
   IdentityFile ~/.ssh/id_ed25519_simple-stack
   ForwardAgent yes

Host instance001.location.region1.provider1.project
   HostName a.b.c.d

Host names should match your Terraform project naming convention, because infrastructure host identities are derived from your Terraform configuration.

Step 2: Start the Platform

Simple Stack runs in Docker Compose with two services:

docker-compose up -d

This starts:

• simple-stack-ui-next – The management UI on http://localhost:3000
• simple-stack-ansible – The execution engine for playbooks and builds

Check that both services are running:

docker-compose ps

Step 3: Create Your First Admin User

1. Open http://localhost:3000
2. Click "Sign In"
3. Use the temporary credentials:
   • Email: admin@example.com
   • Password: ChangeMe123!
4. Create a permanent admin user account
5. Once created, unset the temporary credentials:

unset TEMP_ADMIN_EMAIL
unset TEMP_ADMIN_PASSWORD

You're now ready to start managing infrastructure!

Running Your First Infrastructure Project

Step 1: Create Infrastructure in the UI

1. Log in to http://localhost:3000
2. Go to Infrastructures
3. Click "New Infrastructure"
4. Choose a provider (AWS, OVHcloud, Standalone, etc.)
5. Fill in required variables (account credentials, region, etc.)
6. Click "Create"

The UI generates a Terraform project and shows you the ID and repository path.

Step 2: Deploy your first infrastructure

In this example, your target server can be:

• a Raspberry Pi or any machine hosted at home
• a manually created VPS from a cloud provider.

The provided examples also include OpenStack provisioning flows. More generally, any cloud provider with a Terraform provider is compatible.

Step 2.1: Configure Terraform backend

Navigate to your local terraform project folder:

cd terraform/demo-standalone-instances

Open backend.tf and configure your credentials:

terraform {
  backend "http" {
    address = "http://127.0.0.1:8000/api/tfstates/<YOUR_PROJECT_ID_FROM_SIMPLESTACK_UI>"
  }
}

# Set these as environment variables before terraform plan/apply:
# TF_HTTP_USERNAME=your-email@example.com
# TF_HTTP_PASSWORD=your-password

Step 2.2: Configure Terraform project variables

Create the list of machines to add to the inventory in your terraform.tfvars:

instances = {
   "instance1.location1.region1.provider1.projectName" = {
      provider    = "provider1"
      region      = "region1"
      private_key = "~/.ssh/id_ed25519_simple-stack"
      public_ip   = "1.2.3.4"
      private_ip  = "192.168.1.2"
      port        = "22"
      username    = "ubuntu"
      groups      = ["infrastructure"]
   }
}

Step 2.3: Deploy

Set your credentials and run Terraform:

export TF_HTTP_USERNAME="admin@example.com"
export TF_HTTP_PASSWORD="your-password"

terraform init
terraform plan
terraform apply

Terraform provisions your infrastructure (compute, networking, storage) on your chosen provider.

Step 3: Monitor in the UI

Once terraform apply completes:

1. Return to the UI → Dashboard
2. You'll see a dependency graph showing all provisioned resources

Note: You'll need to configure several variables in the dependency graph nodes (variables, secrets). This step is currently manual and documented in each resource's metadata. [TODO: Better variable documentation and UI hints needed]

Configure Your Infrastructure (Platform Setup)

Step 1: Select Infrastructure

1. Go to Infrastructures
2. Click your infrastructure project
3. Click the project Edit button (Edit variables) to provide context variables for the PaaS Ansible roles.

All project variables are available in the roles, but here is a minimal baseline to get started:

ansible_python_interpreter: /usr/bin/python3
architecture_map:
   aarch64: arm64
   amd64: amd64
   arm64: arm64
   armv7l: arm
   x86_64: amd64
fact_instance:
   datacenter: dc1
   location: '{{inventory_hostname.split(".")[1]}}'
   project: '{{inventory_hostname.split(".")[4]}}'
   provider: '{{inventory_hostname.split(".")[3]}}'
   region: '{{inventory_hostname.split(".")[2]}}'
size:
   large:
      cpu: 256
      memory: 1024
   medium:
      cpu: 128
      memory: 512
   small:
      cpu: 64
      memory: 256
   tiny:
      cpu: 32
      memory: 128
   xl:
      cpu: 512
      memory: 2048
   xxl:
      cpu: 1024
      memory: 4096
ufw_reset: true
ufw_rules:
   - direction: in
      interface: docker0
      rule: allow
   - delete: true
      port: 22
      proto: tcp
      rule: allow
   - from_ip: <your-public-FAI-IP-address>
      port: 22
      proto: tcp
      rule: allow
   - direction: in
      port: 80
      proto: tcp
      rule: allow
   - direction: out
      port: 80
      proto: tcp
      rule: allow
   - direction: in
      port: 443
      proto: tcp
      rule: allow
   - direction: out
      port: 443
      proto: tcp
      rule: allow
upstream_default_arch: "{{architecture_map[ansible_facts.architecture]}}"

Step 2: Run Full Setup

1. Go to Infrastructures
2. Click your infrastructure project
3. Click "Operations" → "Run all playbooks"

This executes Ansible playbooks to:

• Install Nomad, Coredns, Docker and core packages
• Setup networking and firewalls
• Deploy observability stack (Prometheus and exporters)
• Configure SSH access and runners

# The UI triggers this automatically, but you can also run manually:
ansible-playbook playbooks/paas/main.yml -i inventory.py -l instance1.location1.region1.provider1.projectName

Once completed, you are ready to build, publish, and deploy any catalog image.

Build Container Images

Step 1: Build Traefik container

Traefik (reverse proxy and load balancer):

1. Go to Catalogs
2. Find "traefik" → Click "Operations" → "Build"

Step 2: Build Docker registry container

Docker Registry (private image storage):

1. Go to Catalogs
2. Find "docker-registry" → Click "Operations" → "Build"

Deploy Core Services

Step 1: Deploy Traefik

Traefik handles all external traffic and routing:

1. Go to Softwares
2. Click "New Deployment"
3. Catalog: "traefik"
4. Instance: Your created instance
5. Configure:
   • Dashboard username/password
   • External domain (optional)
6. Click "Deploy"

Step 2: Deploy Docker Registry

Docker registry will alloy you to deploy all others docker images you will need to build.

1. Go to Softwares
2. Click "New Deployment"
3. Catalog: "docker-registry"
4. Instance: Your created instance
5. Configure variables:
   • Dashboard username/password
   • External domain (optional)
6. Click "Deploy"

Next Steps

• Infrastructures – Manage cloud resources with Terraform
• Catalogs – Build and organize your application library
• Softwares – Deploy and operate services

Troubleshooting