Forem Creators and Builders

loading...
Cover image for Self Host: Quick Start in Depth
Forem Core Team

Self Host: Quick Start in Depth

Christina Gorton
Developer Advocate, Technical Writer, and Instructor.
・Updated on ・5 min read

This is a walkthrough of the Quick Start section in the Forem selfhost repository.

If you do not have the necessary requirements mentioned in the Requirements section of the selfhost repository please check out the Installing Forem Requirements for MacOS guide for a more in-depth walk through on how to add them all.

Clone Repo and Install Requirements

1.) In your terminal, clone the forem/selfhost repo to your local computer:
git clone https://github.com/forem/selfhost.git

2.) After you have cloned the repository, change into the selfhost directory with:
cd selfhost
3.) Once you are in the selfhost directory, you can install the necessary requirements for Forem with:
pip3 install -r requirements.txt

Generate Ansible Vault Password

1.) After the requirements are installed, you will need to generate an Ansible Vault password.
This password will be used by Ansible as a variable throughout the Forem project. In your terminal type:
pwgen -1 24|tee ~/.forem_selfhost_ansible_vault_password

setup.yml

1.) Open the selfhost directory in your preferred code editor.

2.) Look in the directory selfhost/inventory/example. You should see a file called setup.yml.

3.) Copy the whole file.

4) In the selfhost/inventory/forem folder create a new file called setup.yml and paste in the contents of the selfhost/inventory/example/setup.yml file.

Ansible Inventory Variables

1.) 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)

Example:
Ansible inventory variable examples

Ansible Inventory Secrets

1.) Generate and save Ansible Inventory secrets using the ansible-vault encrypt_string provided in the setup.yml.

While still in your selfhost directory, use the following example commands in a terminal to generate the required variables with Ansible Vault encrypt_string
Note: See this URL to learn more about ansible-vault:

2.) vault_secret_key_base: use this command to create a variable for the vault_secret_key_base:

echo -n $(pwgen -1 128)|ansible-vault encrypt_string --stdin-name vault_secret_key_base
Enter fullscreen mode Exit fullscreen mode

generated vault_secret_key_base

Copy the generated key and add it to your setup.yml file. Be sure to add proper indentation like the example here:
generated key in setup.yml

3.) vault_imgproxy_key: use this command to create a variable for the vault_imgproxy_key:

echo -n $(xxd -g 2 -l 64 -p /dev/random | tr -d '\n') | ansible-vault encrypt_string --stdin-name vault_imgproxy_key
Enter fullscreen mode Exit fullscreen mode

generated vault_imgproxy_key

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

4.) vault_imgproxy_salt: use this command to create a variable for the vault_imgproxy_salt:

echo -n $(xxd -g 2 -l 64 -p /dev/random | tr -d '\n') | ansible-vault encrypt_string --stdin-name vault_imgproxy_salt
Enter fullscreen mode Exit fullscreen mode

generated vault_imgproxy_salt

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

5.) vault_forem_postgres_password: use this command to create a variable for the vault_forem_postgres_password:

echo -n $(pwgen -1 128)|ansible-vault encrypt_string --stdin-name vault_forem_postgres_password
Enter fullscreen mode Exit fullscreen mode

generated vault_forem_postgres_password

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

Generate a SSH Key

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:

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

$ ssh-keygen -t ed25519 -C "your_email@example.com"

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

  1. 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

  2. After you have saved the file you can change it's 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.*

  1. In your terminal type ls -lh ~/.ssh/forem* to ensure you have both a ${HOME}/.ssh/forem private key and a corresponding ${HOME}/.ssh/forem.pub public key.

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:

  1. 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.

  1. Press the ENTER key to accept the default location.

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

  3. 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.

  4. In your terminal, type ls -lh ~/.ssh to confirm you have both your id_rsa private key and id_rsa.pub public key.

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.

After you follow the instructions for the choose cloud provider you will need to set up DNS

DNS

  1. You will need to create an A record and point DNS at the IP address that is output at the end of the provider playbook.

You can see an example of how I set an A record for my namecheap domain below:

In Advanced DNS I added an A record for my domain and subdomain and set the value to the IP address that was outputted after provisioning. I also set TTL to 1minute.
This will defer depending on where your DNS is hosted.
DNS setup on namecheap.com

Forem Traefik Service

Once DNS is pointed at your Forem VM, you will need to restart the Forem Traefik service.

  1. You will need to run the command via SSH. In your terminal type: ssh core@<SERVER IP ADDRESS> replacing with your community name. In the example below I am using my community: ssh core@<SERVER IP ADDRESS example
  2. You may be prompted to continue. Type yes in to your terminal.
  3. Once you have connected to your Forem server type the following command:
    sudo systemctl restart forem-traefik.service
    systemctl restart forem-traefik.service command in terminal

  4. Now, you can navigate to your community domain and you should see a Let's Start your Forem Journey page. You may need to wait a few minutes after running the Forem Traefik command.
    Forem welcome screen

Congratulations on setting up your first Forem!πŸŒ±πŸŽ‰

For more details on how to configure your Forem please visit our Forem Admin Docs.

Discussion (5)

Collapse
steelwolf180 profile image
Max Ong Zong Bao

Nice I think it will be good to update the readme to reflect the changes for this quick start guide as it took me while to figure it out.

Collapse
coffeecraftcode profile image
Christina Gorton Author

Hey @steelwolf180 which part do you think would help if it would in the ReadMe? All of it? A certain section?
We are definitely up for making improvements to the selfhost docs. I will be updating the Quick Start section with a link to this tutorial soon. Do you think that would be sufficient?

Collapse
steelwolf180 profile image
Max Ong Zong Bao • Edited

Yup I believe most of this article can be quite relevant as I had the same issues like the indentation for the config file is something I was scratching my head when I was getting error for it.

Collapse
ellativity profile image
Ella Ang (she/her/elle)

Thanks so much for sharing this in-depth primer, @coffeecraftcode ! Looking forward to welcoming all the new Forems to the fold!

Collapse
drahmedali profile image
drahmedali

Will anyone gonna make a video as installation guide "plz using Windows"?