diff --git a/docs/getting-started/installation/linux.md b/docs/getting-started/installation/linux.md index f59c0c0..3034e99 100644 --- a/docs/getting-started/installation/linux.md +++ b/docs/getting-started/installation/linux.md @@ -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. 1. Clone your forked repository, e.g. `git clone https://github.com//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 @@ -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