Forem Self-Host

Forem is open-source software for building modern and independent communities for your developers, peers, customers, and users. Forem is already powering communities that serve over 10 million monthly unique visitors. Build your community on top of Forem's rock-solid open-source foundation.
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.

How can Forem help you?

• Distribute your content
• Reach more developers
• Grow your community

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

**Apart from a Self-Hosted Forem there is also an enterprise solution called Forem Cloud; no technical setup is required.

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.

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 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 is 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 the 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 the 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 provider, you will need to point DNS at the IP address that is output at the end of the provider playbook.
9. Once DNS is pointed at your Forem VM, you will need to restart the Forem Traefik service (sudo systemctl restart forem-traefik.service) via SSH on your Forem server to generate a TLS cert.
10. Go to your Forem domain name and create your first account. Please see the Forem Admin documentation located here for more information on setting up your Forem.

Provisioning Targets

Note about recommended instance types and cost: For each hosted provisioning target below, we attempted to recommend an instance type with 2 CPUs, 2GB of RAM, and a monthly cost of around USD 15. Please note that providers may charge additionally for disk space, network usage, etc, so your price per month may vary based on your Forem's usage and needs. For exact and specific pricing information, please see each provider directly.

Congratulations! 👍🛌🏽💅🏽🎑
You have successfully installed and configured Forem!

Ref: https://github.com/forem/selfhost