Self Host: Quick Start in Depth

Introduction

In this guide you will learn how to:

• Clone the self-host repository
• Run the automated script to install dependencies
• Edit the setup.yml file
• Setup SSH access to your cloud provider of choice For steps 6-10 in the Quick Start guide please see our cloud provider specific guides.
• AWS
• Google Cloud
• DigitalOcean

Prerequisites

• This guide is for self-host instances on MacOS.
• Before starting this guide be sure to have all the requirements from the Installing Forem Requirements for MacOS installed.

Step 1- Cloning the Self-host Repo

In this step you will clone the self-host repository.

In your terminal, clone the forem/selfhost repo to your local computer with:

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

Step 2- Running the Automated Script

In this step you will run the automated script we have in place to perform several of the necessary setup tasks for you.

Note: If you would prefer to manually set up steps If you would prefer to set up these tasks manually please see the manual installation instructions in the self-host repository.

In your terminal change directories to selfhost with:
cd selfhost

In your terminal run the setup script with:
./setup

The output will look like this:

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

You should see generated vault secrets. Save these to add to the setup.yml file in step 4.

Step 3- Editing the Ansible Inventory Variables

In this step you will edit select Ansible inventory variables to make the Forem instance your own. You will change the default email to use an email you prefer. You will add your own domain name, subdomain. You will also add a preferred host which is used as the server host name to send email server side.

In the selfhost/inventory/forem/setup.yml file, 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)

Note: You can leave the subdomain and hostname as the defaults www and host if you prefer.

Example:

Step 4 - Adding the Ansible Vault Secrets
In this step you will use the Ansible vault secrets generated with the automated setup script. You will replace the example secrets in the setup.yml file.

Note: See this URL to learn more about ansible-vault.

Copy the generated vault_secret_key_base secret and add it to your setup.yml file.

Add proper indentation like the example here:

Copy the vault_improxy_key secret and add it to your setup.yml file like you did with the vault_secret_key_base secret.

Copy the vault_imgproxy_salt secret and add it to your setup.yml file.

Copy the vault_forem_postgres_password secret and add it to your setup.yml file.

Step 5- Generating a SSH Key

DigitalOcean or Google Cloud

If you choose to use DigitalOcean or Google Cloud, you will need to generate a SSH key and save it to ${HOME}/.ssh/forem .

You can follow the Github tutorial on how to create an SSH key or the steps below:

In your terminal paste the text below, substituting in your GitHub email address.

$ ssh-keygen -t ed25519 -C "[your_email@example.com](mailto:your_email@example.com)"

This creates a new ssh key, using the provided email as a label.

When you're prompted to "Enter a file in which to save the key," press Enter. This accepts the default file location. copy the default location that is in your terminal. ex: /Users/you/.ssh/id_ed25519

After you have saved the file you can change its location to ${HOME}/.ssh/forem with the following command:

cp /Users/you/.ssh/id_ed25519 ${HOME}/.ssh/forem

Note: replace /Users/you/.ssh/id_ed25519 with the default file location on your computer.*

Use the following command in your terminal to ensure you have both a ${HOME}/.ssh/forem private key and a corresponding ${HOME}/.ssh/forem.pub public key:

ls -lh ~/.ssh/forem*

AWS RSA based SSH key

If you use AWS, you will need to generate an RSA-based SSH key and save it to the file path ~/.ssh/id_rsa.pub

To generate an RSA based SSH keys in macOS, follow these steps:

In your terminal type:

ssh-keygen -t rsa

When you execute this command, the ssh-keygen utility prompts you to indicate where to store the key.

Press the ENTER key to accept the default location.

The ssh-keygen utility prompts you for a passphrase. Please add a secure passphrase.

By default, your private key will be saved to the id_rsa file in the .ssh directory and is used to verify the public key you use.

In your terminal, type:

ls -lh ~/.ssh

This will confirm you have both your id_rsa private key and id_rsa.pub public key.

Conclusion

At this point, you will need to pick a supported cloud provider and set it up on your workstation.

We currently support AWS, DigitalOcean, and Google Cloud.

You can follow the cloud provider specific guides to finish setting up your self-host instance.

• AWS
• Google Cloud
• DigitalOcean