Forem Creators and Builders

Cover image for Self Host: Quick Start in Depth
Christina Gorton for Forem Core Team

Posted on • Updated on

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

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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:
Ansible inventory variable examples

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.

generated vault_secret_key_base

Add proper indentation like the example here:

generated key in setup.yml

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

generated vault_imgproxy_key

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

generated vault_imgproxy_salt

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

generated vault_forem_postgres_password

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)"
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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*
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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.

Discussion (6)

Collapse
ravikrishnappa profile image
Ravi Krishnappa

I'm a Linode devotee after a failure to retake the ownership of my DO droplet. Earlier, my laptop crashed and I had no backup of my private key. DO has a feature to login from their web and remove the public key but it never worked.

Does this work for Linode hosts? If so, anything special I should remember?

Collapse
drahmedali profile image
drahmedali

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

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!