This repo is out of date, and is no longer the best path for self-host. We will update to provide new instructions in near future (Early 2026)

Forem Self-Host

This is a repo for setting up a free, self-managed install of Forem on a Fedora CoreOS VM running on one of a few popular cloud providers (current support for DigitalOcean, AWS, and Google Cloud). Local development is also supported using a VM on Linux via QEMU.

Please note that Forem is a complex piece of software, and hosting and managing it in a cloud environment is non-trivial. While the recipes and scripts here are expected to work for the limited scenarios we tested against, use and modification of the recipes, or altering the deployed environment, may require familiarity with the following layers of the tech stack we built with, and ongoing maintenance of the deployed system may require interacting with any of these technologies:

• Ansible
• Your chosen cloud provider - both CLI and UI use
• Python 3 and pip3
• systemd
• Podman
• General Linux administration, especially Fedora CoreOS, including:
  • Butane
  • Ignition

If a Self-Hosted Forem is not right for you, we offer a fully-managed, enterprise solution called Forem Cloud; no technical setup required. For more information, please contact us via this form.

For those that want to DIY beyond the scope of this repo, you can use the systemd units in the Butane template as an example of how to run Forem without Fedora CoreOS on a Linux distribution that supports systemd, or customize that template to fit your needs or create a bootable Ignition configuration to consume on bare metal or in a custom VM.

The goal of this project is to provide you with the choice, freedom, and cost-effectiveness to host your own Forem community as you see fit.

We can't wait to see the community you selfhost with Forem!

Table of Contents

• Forem Self-Host
  • Requirements
  • Quick Start
    • Semi-automated setup
    • Manual installation
  • Provisioning Targets
    • AWS
      • Setup
      • Provision
    • DigitalOcean
      • Setup
      • Provision
    • Google Cloud
      • Setup
      • Provision
  • Ansible Dynamic Inventories
    • AWS
    • DigitalOcean
    • Google Compute
  • Configuration Internals
    • systemd
    • Forem configs
  • SSH Examples
    • foremctl
    • Update Forem to the latest version and restart
    • foremimg
    • Set the Forem container repository and tag
    • Update Forem to the latest version with no restart
    • Rollback Forem to the last running version and restart
    • Update Fedora CoreOS to the latest stable version
    • Backup your Forem data
  • Development
    • Install Dependencies
      • SSH Key
      • SSH Config
      • Ansible Vault
      • Create Forem Ansible Inventory
      • Launch Forem Locally
      • Local SSH Access

Requirements

• Git
• Python 3.x and pip3
  • macOS: brew install python3

  Note: This will likely use Python 3 at /usr/local/bin/python3, not /usr/bin/python3, requiring that you set ansible_python_interpreter to /usr/local/bin/python in inventory or via extra vars (eg -e ansible_python_interpreter=/usr/local/bin/python)

• Ansible: ansible-core 2.11 or greater (provided by Ansible 4.0.0)
• Butane
  • Mac OS: brew install butane
• pwgen
  • Mac OS: brew install pwgen
• Fedora CoreOS, running on the Stable stream
• A supported cloud provider, bare metal server, or a VM in QEMU.

Note: Some provisioning targets have additional requirements that are detailed out in each respective section.

Quick Start

Note: Following this quick start guide with the cloud provider of your choice will cost you money! Please consult with each cloud provider to figure out how much your Forem will cost you per month.

Start by cloning the forem/selfhost repository to your local computer and change into the newly created directory:

git clone https://github.com/forem/selfhost.git
cd selfhost

After this step you have two choices: a semi-automated setup via a script or a completely manual installation.

Semi-automated setup

We have a script in place that will perform several of the necessary setup tasks for you. It will take care of the first 3 steps of the manual installation process (installing Python dependencies, generating an Ansible Vault password and copying the inventory definition for you). It will also generate the secrets needed for step 4.

./setup

Verifying that pip is available

Installing Python dependencies
[output omitted]

Generating Ansible Vault secret
ixooGe3ob0shob8soo6AhYie

Copying example inventory
'inventory/example/setup.yml' -> 'inventory/forem/setup.yml'

Generating Vault secrets
[output omitted]

Use these secrets to replace the placeholders in inventory/forem/setup.yml

Once the script finished running, continue from step 4. of the manual installation process described below.

Manual installation

1. Install Python dependencies:
   • System-wide:
     • pip3 install -r requirements.txt
   • In a virtual environment: create a virtual env first, then enter it before installing the dependencies. Then remain in the virtual env unless you're done with the setup process. Example with Python 3's native venv module:
     • python3 -m venv /path/to/new/virtual/environment
     • source <venv>/bin/activate
     • pip3 install -r requirements.txt
     • perform rest of setup
     • deactivate (leaves the virtual env)
2. Generate an Ansible Vault password
   • mkdir -p ~/.config/forem
   • pwgen -1 24|tee ~/.config/forem/selfhost_ansible_vault_password
3. Copy example Ansible Inventory from inventory/example/setup.yml to inventory/forem/setup.yml
4. Edit inventory/forem/setup.yml Ansible Inventory with your Forem settings
   • Edit the following Ansible inventory variables:
     • default_email (Admin Email for system to use)
     • forem_domain_name (A domain name that you own and set A records on at your DNS provider)
     • forem_subdomain_name (defaults to www)
     • forem_server_hostname (defaults to host)
   • If you used the setup script you can use the previously generated inventory secrets here. Otherwise, you have to use ansible-vault encrypt_string to create the secrets listed below. See "Required Ansible Vault secret variables" in the example setup.yml, which contains the required commands to generate each variable's value:
     • vault_secret_key_base
     • vault_imgproxy_key
     • vault_imgproxy_salt
     • vault_forem_postgres_password
5. Setup SSH access for your cloud provider
   • If you choose to use DigitalOcean or Google Cloud as your cloud provider, you will need to generate a SSH key and save it to ${HOME}/.ssh/forem. Use ls -lh ~/.ssh/forem* to ensure you have both a ${HOME}/.ssh/forem private key, and a corresponding ${HOME}/.ssh/forem.pub public key.
   • If you use AWS as your cloud provider, you will need to generate an RSA-based SSH key and save it to the file path ~/.ssh/id_rsa.pub. Please visit the AWS RSA based SSH key section in our Self Host: Quick Start in Depth guide for instructions on creating an RSA-based key.
6. Pick a supported cloud provider and set it up on your workstation
   • AWS
   • DigitalOcean
   • Google Cloud
7. Run the Ansible Playbook for your chosen cloud provider
   • AWS
   • DigitalOcean
   • Google Cloud
8. Once your Forem VM is set up with your chosen cloud provide