Hey,
I got myself the new Mac M1 as I was excited about the new (ARM) architecture finally arriving on desktops. While my primary development platform remains a Linux box, I was curious if Foreman can run on Mac. And indeed it starts up, not all features will definitely work as we only write and test everything for Linux, but chances are that people who are on a Mac will be able to contribute. For example basic WebUI development or running snapshot rake task does work.
This tutorial is shorten version of our Contribute guide so make sure to check it out for more details. Since I am not using this setup for my own development, this page can get outdated, so I am turning this into a wiki - feel free to update it if you find problems.
Warning: This is a tutorial for setting up custom Ruby and NodeJS versions on MacOS. For similar tutorial but on Linux see this post.
Clone Foreman repository:
git clone https://github.com/theforeman/foreman
cd foreman
Find out which Ruby on Rails is currently in use:
grep rails Gemfile
At the time of writing, it is Rails 6.0. Search the interned and find which Ruby version is supported, that is the supported Ruby version you should install. For Rails 6.0 it is Ruby 2.5 or 2.6 or 2.7. If any of these version is available your distribution, then stop reading right here and follow our Contributing guide to install the Ruby for your OS - there is no need to install Brew.
For NodeJS, we usually support latest stable version and likely one major version older one. At the time of writing this it is v14 and v13. If you also have this verison in your OS, there is no need to follow this guide.
Make sure you have Homebrew installed, I am pretty sure you already have that because that is absolutely essential thing to have on a Mac. Now, install Ruby and NodeJS and make sure to specify the correct versions:
brew install ruby@2.7 node@14 libvirt
Note we need to install libvirt libraries (and service) in order to compile libvirt Ruby client library, but do not worry libvirt service will not be started or used. After installation instructions will be printed to add another commands to your profile - brew does not put software into PATH by default:
echo 'export PATH="/opt/homebrew/opt/ruby@2.7/bin:/opt/homebrew/lib/ruby/gems/2.7.0/bin:$PATH"' >> $HOME/.bash_profile
echo 'export PATH="/opt/homebrew/opt/node@14/bin:$PATH"' >> $HOME/.bash_profile
Source the profile (or logout and login back), in the Foreman dir perform the following commands:
bundle install --without="journald service" --path=vendor/
npm install
Note some bundle groups were disabled, I haven’t tested them as they might not compile correctly. Feel free to edit .bundler/config and remote those groups which you intend to use.
Let’s install PostgreSQL. I haven’t tested this part myself as I used an existing database running on a remote Linux server, so I just copy pasted this from a different tutorial:
brew install postgres
initdb /usr/local/var/postgres
pg_ctl -D /usr/local/var/postgres start
createuser -s foreman
createdb -O foreman foreman-dev
createdb -O foreman foreman-test
Configure Foreman, make sure to review and edit both files setting up database name to foreman-dev and foreman-test:
cp config/settings.yaml.example config/settings.yaml
cp config/database.yml.example config/database.yml
Migrate and seed the database and reset password which is random by default:
bundle exec rake db:migrate
bundle exec rake db:seed
be rake permissions:reset password=changeme
At this point, the development setup is be ready, you can run tests, run various rake tasks. Before running our test suite, you want to increase maximum limit of opened files:
ulimit -S -n 4096
It is necessary to recompile JS assets prior running integration tests:
bundle exec rake webpack:compile
To run tests perform:
bundle exec rake test
Another example is generating template snapshots to make template changes to pass tests:
RAILS_ENV=test bundle exec rake snapshots:generate
To start Ruby on Rails and Webpack via NodeJS, two processes must be started. We use “foreman” gem to start them both:
foreman start
More information can be found in our Contributing guide. This page is a wiki, feel free to update this as things will get old over time.