Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

More explicit dev setup instructions #9906

Merged
merged 2 commits into from
Feb 19, 2024
Merged

More explicit dev setup instructions #9906

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
68d711b
Correct the minimum PostgreSQL version
ekohl Nov 15, 2023
83e4186
More explicit dev setup instructions
ekohl Nov 15, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
90 changes: 55 additions & 35 deletions developer_docs/foreman_dev_setup.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,25 +10,55 @@ Foreman will run with the following requirements (aside from rubygem dependencie
* Ruby 2.7.x
* NodeJS 14
* NPM 6.x
* PostgreSQL 13
* PostgreSQL 10+ (12+ recommended)

It’s recommended to install https://github.com/rbenv/rbenv[rbenv] or https://github.com/rvm/rvm[rvm] to manage ruby, and https://github.com/nvm-sh/nvm[nvm] to manage node and npm on your system.
* For Fedora users, you can use this https://developer.fedoraproject.org/start/sw/web-app/rails.html[guide] for installing: rbenv, Ruby & Bundler.
(There is no need to install Rails, as it is installed by Bundler when running `bundle install` from Foreman directory).
https://github.com/rbenv/rbenv[rbenv] or https://github.com/rvm/rvm[RVM] can be used to install compatible Ruby versions. Similarly, https://github.com/nvm-sh/nvm[nvm] can be used to manage node and npm on your system.

Before installing PostgreSQL, check first that you don't already have it installed (by running `rpm -q postgresql`).
=== Fedora

You will want to make sure that you have postgresql-devel installed so the database gems can install properly.
Also, you would also need gcc, ruby-devel, libxml-devel, libxslt-devel and libvirt-devel packages.
Fedora ships with a too new Ruby. It's recommended to install https://github.com/rbenv/rbenv[rbenv] to install a compatible version:

[source, bash]
....
sudo dnf install rbenv ruby-build-rbenv nodejs
echo 'eval "$(rbenv init -)"' >> ~/.bashrc
source ~/.bashrc
rbenv install 2.7.6
Griffin-Sullivan marked this conversation as resolved.
Show resolved Hide resolved
....

https://github.com/rvm/rvm[RVM] can also be used.

=== Enterprise Linux 8

By default EL8 ships with older versions, but newer modules are available:

[source, bash]
....
dnf module enable ruby:2.7
dnf module enable postgresql:12
dnf module enable nodejs:14
....

Now install the development packages:

For Fedora, CentOS or RHEL, you can issue the following commands to install all required packages:
[source, bash]
....
dnf groupinstall "Development Tools" "Development Libraries"
dnf -y install gcc-c++ git ruby ruby-devel rubygems \
dnf -y install gcc-c++ git ruby ruby-devel rubygem-bundler \
libvirt-devel postgresql-devel openssl-devel \
libxml2-devel libxslt-devel zlib-devel \
readline-devel systemd-devel tar libcurl-devel
readline-devel systemd-devel tar libcurl-devel nodejs
....

=== PostgreSQL

Use the following steps to set up PostgreSQL on RPM based distributions:

[source, bash]
....
sudo dnf install postgresql
sudo postgresql-setup --initdb
sudo -u postgres createuser --createdb $USER
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Do you need to be in a specific directory to run this?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

No, that shouldn't matter. I have seen warnings when the postgres user can't chdir to $PWD, but that's only a warning.

....

[[Setup]]
Expand All @@ -41,7 +71,19 @@ cd foreman
cp config/settings.yaml.example config/settings.yaml
cp config/database.yml.example config/database.yml
git remote add upstream [email protected]:theforeman/foreman.git
gem install bundler
....

If you're using rbenv, now you can configure it to locally use Ruby 2.7:

[source, bash]
....
rbenv local 2.7.6
....

Now you can install the dependencies:

[source, bash]
....
bundle install
npm install
....
Expand All @@ -68,36 +110,14 @@ Foreman uses Bundler to install dependencies and get up and running. This is the
It is important that config/database.yml is set to use the correct database in the “development” block.
Rails (and subsequently Foreman) will use these connection settings under “development” to manage the database it uses and setup the necessary schema.

If the default version of the database.yml file isn't working for you, try editing it with the following:
[source, ruby]
....
development:
adapter: postgresql
host: localhost
username: postgres
password: password
pool: 5
database: foreman_development

test:
adapter: postgresql
host: localhost
username: postgres
password: password
pool: 5
database: foreman_test
....

Set up database schema, precompile assets and locales:
Set up database schema:
[source, ruby]
....
bundle exec rake db:create # if not already created
bundle exec rake db:migrate
bundle exec rake db:seed
SEED_ADMIN_PASSWORD=changeme bundle exec rake db:seed
....

The db:seed step will print out the default admin password, record this in order to log in later.

The previous commands will create databases only for the development environment, for test environment you need to run also:
[source, ruby]
....
Expand Down
Loading