diff --git a/README_MACOSX_NOTES.md b/README_MACOSX_NOTES.md index b42b826cc4..a820fcf10c 100644 --- a/README_MACOSX_NOTES.md +++ b/README_MACOSX_NOTES.md @@ -1,14 +1,45 @@ -The following is the beginning of a native MacOSX setup script. -It is based on @mo-nathan's notes while getting his local Apple M1 -working under the Monterey (12.4) version of MacOS. -It also includes some notes later added by @nimmolo, and by -@JoeCohen when getting his local Apple Intel working under MacOS Ventura 13.6 - -### Install Xcode +Setup MacOSX Development Environment + +This the start of a native MacOSX setup script. +It is based on @mo-nathan's notes for his local Apple M1 with MacOS Monterey (12.4). +It includes notes later added by @nimmolo, and by +@JoeCohen for his local Apple Intel with MacOS Ventura 13.6 +though Sequoia 15.2. + +- [Install Needed Tools](#install-needed-tools) + - [Xcode](#xcode) + - [Xcode Command Line Tools](#xcode-command-line-tools) + - [homebrew](#homebrew) + - [WARNING: Older macOS or Mac hardware](#warning-older-macos-or-mac-hardware) + - [Install a bunch of useful stuff from Homebrew](#install-a-bunch-of-useful-stuff-from-homebrew) + - [WARNING: Previously Installed Versions Of MySQL](#warning-previously-installed-versions-of-mysql) + - [Bash](#bash) + - [Configure MySQL](#configure-mysql) + - [IMPORTANT](#important) +- [Obtain and configure MO](#obtain-and-configure-mo) + - [Clone the MO repo](#clone-the-mo-repo) + - [Switch to the cloned repo](#switch-to-the-cloned-repo) + - [Make sure you have the current version of Ruby](#make-sure-you-have-the-current-version-of-ruby) + - [chruby](#chruby) + - [rbenv](#rbenv) + - [Load an MO database snapshot](#load-an-mo-database-snapshot) + - [Run the rest of the mo-dev script](#run-the-rest-of-the-mo-dev-script) + - [Install trilogy](#install-trilogy) + - [Continue the mo-dev script](#continue-the-mo-dev-script) + - [Prevent direct commits to the main branch](#prevent-direct-commits-to-the-main-branch) + - [Ruby upgrade with chruby](#ruby-upgrade-with-chruby) + - [Other](#other) +- [Footnotes](#footnotes) + +Table of contents generated with markdown-toc + +# Install Needed Tools + +## Xcode Get Xcode (free download from the [App Store](https://www.apple.com/app-store/)) -### Install Xcode Command Line Tools +## Xcode Command Line Tools install the command line tools with: @@ -16,7 +47,13 @@ install the command line tools with: xcode-select --install ``` -### Install homebrew +## homebrew + +### WARNING: Older macOS or Mac hardware + +**Do not update Homebrew or MySQL if you have older hardware or macOS < 11. +MySQL 9 will not install in any case on older Macs.** + You will also need `homebrew` from : @@ -31,34 +68,19 @@ brew outdated brew upgrade ``` -#### Important: -If you have mysql < 9.0 installed remove mysql and all vestiges before continuing. +## Install a bunch of useful stuff from Homebrew -- `ps -ax | grep mysql` -- stop and kill any MySQL processes -- `brew remove mysql` -- `brew cleanup` -- `sudo rm /usr/local/mysql` -- `sudo rm /etc/my.cnf` -- `sudo rm /usr/local/etc/my.cnf` -- `sudo rm -rf /usr/local/var/mysql` -- `sudo rm -rf /usr/local/mysql*` -- `sudo rm ~/Library/LaunchAgents/homebrew.mxcl.mysql.plist` -- `sudo rm -rf /Library/StartupItems/MySQLCOM` -- `sudo rm -rf /Library/PreferencePanes/My*` -- edit /etc/hostconfig and remove the line `MYSQLCOM=-YES-` -- `rm -rf ~/Library/PreferencePanes/My*` -- `sudo rm -rf /Library/Receipts/mysql*` -- `sudo rm -rf /Library/Receipts/MySQL*` -- `sudo rm -rf /private/var/db/receipts/*mysql*` +### WARNING: Previously Installed Versions Of MySQL + +**If you have mysql version < 9.0 installed, remove mysql and all its vestiges before +continuing. See footnote 1.[1](#f1)** -Install a bunch of useful stuff from `Homebrew` ```sh brew install git mysql exiftool libjpeg shared-mime-info openssl imagemagick findutils ``` -### Install Bash +## Bash If you haven't done so already, install a recent version of [Bash](https://www.gnu.org/software/bash/) and set it as the default shell. You can find your installed version like this: @@ -100,7 +122,7 @@ Check those versions `/usr/local/bin/bash` should be the new one. -### Configure MySQL +## Configure MySQL Set the root password @@ -109,6 +131,11 @@ brew services start mysql mysqladmin -u root password 'root' ``` +#### IMPORTANT + +> If you cannot set the mysql root password, please contact us +> instead of applying random "solutions" from AI or StackOverflow. + Test the New Password: Verify that the new root password is working: ```sh @@ -118,7 +145,9 @@ mysql -u root -p When prompted, enter the new root password. You should be able to access MySQL with the new password. -### Clone the MO repo. +# Obtain and configure MO + +## Clone the MO repo Make sure you have an up-to-date checkout of this repo in a local directory. Since you're reading this you may have already done that. @@ -134,13 +163,13 @@ git clone git@github.com:MushroomObserver/mushroom-observer.git git clone https://github.com/MushroomObserver/mushroom-observer ``` -### Switch to the cloned repo +## Switch to the cloned repo ```sh cd mushroom-observer ``` -### Make sure you have the current version of Ruby +## Make sure you have the current version of Ruby ```sh if ! [[ `ruby --version` =~ `cat .ruby-version` ]]; then @@ -149,17 +178,21 @@ fi ``` There are various tools for this (rvm, chruby, rbenv). -In the past MO used rvm, but it caused havoc on the vm. We recently switched to rbenv. -@mo-nathan used chruby most recently -because it was already installed. +(In the past MO used rvm, but it caused havoc on the vm.) +@mo-nathan used chruby most recently because it was already installed. + +### chruby + For chruby, run: ```sh -ruby-build $RUBY_VERSION ~/.rubies/ruby-$RUBY_VERSION - chruby $RUBY_VERSION + ruby-build $RUBY_VERSION ~/.rubies/ruby-$RUBY_VERSION + chruby $RUBY_VERSION ``` +### rbenv + @nimmolo and @JoeCohen used rbenv. For rbenv run: (installing ruby-build maybe also needed above) @@ -185,13 +218,15 @@ or for bash: rbenv global $RUBY_VERSION ``` -### Load an MO database snapshot. +### Load an MO database snapshot +- Make sure you have the file `config/database.yml`. + If not, create the file with the content shown in footnote 2.[2](#f2) - download the snapshot from - copy (or move) the downloaded .gz file to the `mushroom-observer` directory. Then: -Mac users have to uncomment/comment the relevant/irrelevant lines in `config/database.yml`: +Mac users must uncomment/comment the relevant/irrelevant lines in `config/database.yml`: ```yml shared: @@ -209,10 +244,6 @@ rake db:drop mysql -u root -p < db/initialize.sql ``` -NOTE: 2024-12-27 @JoeCohen: For me (but not others) `rake db:drop` threw an error -because `config/database.yml` was missing. -Please contact us if that is the case. - When prompted to "Enter password:"
Enter `root`, return. Then: @@ -243,7 +274,7 @@ cp db/macos/database.yml config Optionally delete `checkpoint_stripped.gz` from the mushroom-observer directory -### Run the rest of the mo-dev script +## Run the rest of the mo-dev script (See ) (Both @nimmolo and @JoeCohen did this in pieces.) @@ -303,7 +334,7 @@ fi gem install trilogy ``` -### Continue the mo-dev script +## Continue the mo-dev script ```sh git pull @@ -330,70 +361,161 @@ rm config/credentials.yml.enc EDITOR='echo "test_secret: magic" >> ' rails credentials:edit ``` -Hopefully this is not necessary on a fresh clean system, -but @mo-nathan had to run +Hopefully this is not necessary on a fresh clean system, but +@mo-nathan had to run the following for each version of Ruby in chruby. ```sh -gem pristine --all + gem pristine --all ``` -for each version of Ruby in chruby - -### Prevent commits directly to the main branch +## Prevent direct commits to the main branch -Create a file `.git/hooks/pre-commit` with the following content: +> Create a file `.git/hooks/pre-commit` with the following content: ```sh -#!/bin/sh -branch=$(git rev-parse --abbrev-ref HEAD) -if [ "$branch" = "main" ] -then + #!/bin/sh + branch=$(git rev-parse --abbrev-ref HEAD) + if [ "$branch" = "main" ] + then echo "Do not commit directly to the $branch branch" exit 1 -fi + fi ``` -Ensure that the file is executable: +> Ensure that the file is executable: ```sh -chmod +x .git/hooks/pre-commit + chmod +x .git/hooks/pre-commit ``` -### Ruby upgrade with chruby +## Ruby upgrade with chruby -Install the selected version. +- Install the selected version. +```sh ruby-install ruby 3.3.6 +``` -Once that succeeds, update Ruby versions in .ruby-version and -Gemfile.lock. - -In a new shell run: +- Once that succeeds, update Ruby versions in `.ruby-version` and `Gemfile.lock`. +- In a new shell run: +```sh chruby ruby-3.3.6 bundle install gem pristine --all +``` -In another new shell now run: +- In another new shell now run: +```sh rails t +``` -### Other +## Other You probably need to generate a new development master key (see below) if you get a test failure like this: -```txt +```sh + Stopped processing SimpleCov as a previous error not related to SimpleCov has + been detected ... inat_imports_controller.rb:50:in + : undefined method id for nil (NoMethodError) +``` + +or like this: + +```ruby FAIL ConfigTest#test_secrets (24.96s) Expected: "magic" Actual: nil test/models/config_test.rb:9:in `test_secrets' ``` -@JoeCohen had to generate a new developmemt master key. -In the mushroom-observer directory, create the file -`/config/master.key` with this content: +To generate a new developmemt master key. +In the `mushroom-observer` directory, create the file +`config/master.key` with this content: ```txt 5f343cfc11a623c470d23e25221972b5 ``` + +----- + +# Footnotes + +1. Suggested procedure for removing vestiges of mysql [↩](#a1) + +- `ps -ax | grep mysql` +- stop and kill any MySQL processes +- `brew remove mysql` +- `brew cleanup` +- `sudo rm /.my.cnf` +- `sudo rm /.mysql_history` +- `sudo rm /etc/my.cnf` +- `sudo rm /usr/local/etc/my.cnf.default` +- `sudo rm -rf /usr/local/etc/my.cnf` +- `sudo rm -rf /usr/local/var/mysql` +- `sudo rm -rf /usr/local/mysql*` +- `sudo rm ~/Library/LaunchAgents/homebrew.mxcl.mysql.plist` +- `sudo rm -rf /Library/StartupItems/MySQLCOM` +- `sudo rm -rf /Library/PreferencePanes/My*` +- `rm -rf ~/Library/PreferencePanes/My*` +- `sudo rm -rf /Library/Receipts/mysql*` +- `sudo rm -rf /Library/Receipts/MySQL*` +- `sudo rm -rf /private/var/db/receipts/*mysql*` +- edit /etc/hostconfig and remove the line `MYSQLCOM=-YES-` + +2. Content of `/config/database.yml` [↩](#a2) + +```yml +# This file should not be checked into subversion + +# MySQL (default setup). +# +# Get the fast C bindings: +# gem install trilogy +# (on OS X: gem install mysql -- --include=/usr/local/lib) + +shared: + adapter: trilogy + # Default (works for MacOS X) + socket: /tmp/mysql.sock + # For Ubuntu/Debian + # socket: /var/run/mysqld/mysqld.sock + # For Fedora + # socket: /var/lib/mysql/mysql.sock + # Connect on a TCP socket. If omitted, the adapter will connect on the + # domain socket given by socket instead. + #host: localhost + #port: 3306 + # For mysql >= 5.7.5 + # Do not require SELECT list to include ORDER BY columns in DISTINCT queries, + # And do not not require ORDER BY to include the DISTINCT column. + variables: + sql_mode: TRADITIONAL + +development: + primary: + database: mo_development + username: mo + password: mo + cache: + database: cache_development + username: mo + password: mo + host: localhost + migrations_paths: "db/cache/migrate" + +# Warning: The database defined as 'test' will be erased and +# re-generated from your development database when you run 'rake'. +# Do not set this db to the same as development or production. +test: + database: mo_test + username: mo + password: mo + +production: + database: mo_production + username: mo + password: mo +```