Skip to content

Commit

Permalink
installation/linux: Faster onboarding with rtx and simplified daemons.
Browse files Browse the repository at this point in the history
  • Loading branch information
@klardotsh
klardotsh committed Sep 11, 2023
1 parent 0ddc44c commit a326dd2
Showing 1 changed file with 85 additions and 84 deletions.
169 changes: 85 additions & 84 deletions docs/getting-started/installation/linux.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,76 +4,50 @@ sidebar_position: 3

# Linux

**Installing Forem on Linux**

## Installing prerequisites

_These prerequisites assume you're working on a Linux-based operating system,
but they have only been tested on Ubuntu 18.04._

### Ruby

1. If you don't already have a Ruby version manager, we highly recommend
[rbenv](https://github.com/rbenv/rbenv). Please follow their
[installation guide](https://github.com/rbenv/rbenv#installation).
1. With the Ruby version manager, install the Ruby version listed on our badge.
(ie with rbenv: `rbenv install $(cat .ruby-version)`)

For very detailed rbenv installation directions on several distros, please visit
[DigitalOcean's guide](https://www.digitalocean.com/community/tutorials/how-to-install-ruby-on-rails-with-rbenv-on-ubuntu-18-04).

### Yarn

There are two ways to install Yarn.

- Yarn's official
[installation guide](https://yarnpkg.com/en/docs/install#debian-stable)
(recommended).
- [DigitalOcean's detailed tutorial](https://www.digitalocean.com/community/tutorials/how-to-install-node-js-on-ubuntu-18-04)
describes how to install
[Node version Manager](https://github.com/creationix/nvm). By installing NVM
you can select a Node version, use `16` (matches Forem's .nvmrc and package.json files);
the guide will also explain how to install NPM. This way you'll have Node, NPM, and then
you can run `npm install -g yarn` to install Yarn.

### PostgreSQL

Forem requires PostgreSQL version 11 or higher.

1. Run
`sudo apt update && sudo apt install postgresql postgresql-contrib libpq-dev`.
1. To test the installation you can run `sudo -u postgres psql` which should
open a PostgreSQL prompt. Exit the prompt by running `\q` then run
`sudo -u postgres createuser -s $YOUR_USERNAME` where `$YOUR_USERNAME` is the
username you are currently logged in as.

There are more than one ways to setup PostgreSQL. For additional configuration,
check out our [PostgreSQL setup guide](postgresql.md) or the official
[PostgreSQL](https://www.postgresql.org/) site for further information.

### ImageMagick

Forem uses [ImageMagick](https://imagemagick.org/) to manipulate images on
upload.

Please refer to ImageMagick's
[instructions](https://imagemagick.org/script/download.php) on how to install
it.

### Redis

Forem requires Redis version 6.0 or higher.

We recommend following Digital Ocean's extensive guides
[How to Install and Secure Redis](https://www.digitalocean.com/community/tutorial_collections/how-to-install-and-secure-redis)
to setup Redis.

## Installing Forem
**Installing Forem on Bare-Metal Linux**

> As the title implies, this spins up a Forem stack for local development with no use of containerization, virtualization, etc., which comes with tradeoffs: standing the stack up will almost invariably be a slower process as various tools build from source, but attaching debuggers and the like to the resulting Forem application may be easier. If using containers through Docker or Podman isn't a deal-breaker for your usecase, [consider those docs instead](containers.md) for faster stand-up and teardown, and to leave less cruft behind when you're done working.
_For maintainer sanity reasons, this opinionated and curated instruction set assumes you're cool with the use of user-local installations of all dependencies using [rtx](https://github.com/jdx/rtx) as a project-scoped package manager. If `rtx` is for any reason a non-starter for you, you'll want to use your package management solutions of choice to install the tools found in `.rtx.toml`, `.ruby-version`, and `.nvmrc`, at the appropriate versions, and should be comfortable sorting out the dependencies thereof on your own. The instructions were written for Debian 12 (Bookworm), but should be directly usable on Ubuntu, Mint, and other Debian derivatives, and should be adaptable for other distributions._

## Install System-Level Dependencies

- [rtx](https://github.com/jdx/rtx)
- [ImageMagick](https://imagemagick.org/), used to manipulate images on upload. Currently, there's not a reliable way to manage this with `rtx`, so you'll need to use your distribution package manager
- A C/C++ compiler, `make`, and so forth. These base development tool bundles go by many names in various distributions: `build-essential` on Debian-alikes, `base-devel` on Arch-alikes, `alpine-sdk`, etc.
- `pkg-config`, which is used to help find system-wide libraries
- `libz` and `libssl` (unless you know your distribution uses something else, this means OpenSSL) development headers
- `git`, to clone the repository
- `curl`, an HTTP (among others) client
- Various transitive dependencies of [PostgreSQL and its compilation](https://github.com/smashedtoatoms/asdf-postgres#dependencies) not already listed above:
* `libreadline-dev`
* `libcurl4-openssl-dev`
* `uuid-dev`
* `icu-devtools`

```sh
# For non-Debian-based Linuxes, see https://github.com/jdx/rtx#installation
sudo install -dm 755 /etc/apt/keyrings
wget -qO - https://rtx.pub/gpg-key.pub | gpg --dearmor | sudo tee /etc/apt/keyrings/rtx-archive-keyring.gpg 1> /dev/null
echo "deb [signed-by=/etc/apt/keyrings/rtx-archive-keyring.gpg arch=amd64] https://rtx.pub/deb stable main" | sudo tee /etc/apt/sources.list.d/rtx.list

sudo apt update
sudo apt install -y imagemagick git curl rtx build-essential pkg-config libssl-dev libz-dev libreadline-dev libcurl4-openssl-dev uuid-dev icu-devtools

# Now configure rtx for your shell:
echo $TERM
# if this says "bash", use:
echo 'eval "$(rtx activate bash)"' >> ~/.bashrc && eval "$(rtx activate bash)"
# if it says "zsh", use:
echo 'eval "$(rtx activate zsh)"' >> ~/.zshrc && eval "$(rtx activate zsh)"
# otherwise, check out the upstream instructions at https://github.com/jdx/rtx#register-shell-hook
```

## Clone And Configure Repository

1. Fork Forem's repository, e.g. <https://github.com/forem/forem/fork>
1. Clone your forked repository, e.g.
`git clone https://github.com/<your-username>/forem.git`
1. Install bundler with `gem install bundler`
1. Set up your environment variables/secrets

- Take a look at `.env_sample`. This file lists all the `ENV` variables we
Expand All @@ -98,26 +72,53 @@ to setup Redis.
export CLOUDINARY_CLOUD_NAME="A_CLOUDINARY_NAME"
```

- You do not need "real" keys for basic development. Some features require
certain keys, so you may be able to add them as you go. The test environment
is isolated from changes to the .env file, if you want to set variables in both
test and development, use a file named .env.local, or modify .env.test.local
and .env.development.local.
- You do not need "real" keys for basic development. Some features require certain keys, so you may be able to add them as you go. The test environment is isolated from changes to the .env file, if you want to set variables in both test and development, use a file named .env.local, or modify .env.test.local and .env.development.local.

## Install Application-Level Dependencies

> If using the `rtx`-managed PostgreSQL isn't ideal for you, there are alternate methods available. Check out our [PostgreSQL setup guide](postgresql.md) or the official [PostgreSQL](https://www.postgresql.org/) site for further information.
> If using the `rtx`-managed Redis isn't ideal for you, there are alternate methods available. Consider DigitalOcean's extensive documentation on [How to Install and Secure Redis](https://www.digitalocean.com/community/tutorial_collections/how-to-install-and-secure-redis).
```sh
# Install node, ruby, yarn, etc.
rtx install
# Install all nodejs dependencies
yarn install --dev
# Start the caching server
redis-server --daemonize yes
# Start and populate the database
pg_ctl start # This should be run every time you work on Forem!
createuser -U postgres -s forem
createdb -U forem forem
./bin/setup # Will also install Ruby gems as necessary
```
## Start Up Your Forem!
```sh
./bin/startup
# Presuming no errors here, your Forem should be accessible at `http://localhost:3000`.
```
To run unit tests, first, prepare the database:
1. Run `bin/setup`
```sh
./bin/rails db:test:prepare RAILS_ENV=test
```
### Possible error messages
Then, try running any test, for example:
While installing, you might run into an error due to the `pg` gem requiring
PostgreSQL libraries. If so, please run `sudo apt-get install libpq-dev` before
retrying.
```sh
./bin/rspec spec/lib/acts_as_taggable_on
```
While installing, you might run into an error due to the `sass-rails` gem
requiring `sassc`, which requires the `g++` compiler. If so, please run
`sudo apt-get install g++` before retrying.
To shut down your Forem stack when you're done tinkering, shut services down in the inverse order of how we started them:

While installing, if you didn't install `node` or `nvm` manually, you might run
into an error due to an older system node version being present, which can cause
issues while `yarn` is installing packages. If so, you'll need to
[install `nvm`](https://github.com/nvm-sh/nvm#installation-and-update) and then
run `nvm install node` to get the most recent node version before retrying.
- Press `Ctrl-C` to stop the Forem server process that's currently in the foreground
- `pg_ctl stop` will shut down the database
- `redis-cli SHUTDOWN` will stop the caching server

0 comments on commit a326dd2

Please sign in to comment.