From a0a495d804319c3f7ad179baba7b87b41f1dc1f3 Mon Sep 17 00:00:00 2001 From: erdgeist Date: Tue, 4 Aug 2026 21:11:25 +0200 Subject: Rework the README/INSTALL documents and provide a bootstrap script (untested ;) --- doc/CUTOVER_2026.md | 348 ++++++++++++++++++++++++++++++++++++++++++++++++++++ doc/INSTALL.md | 341 -------------------------------------------------- 2 files changed, 348 insertions(+), 341 deletions(-) create mode 100644 doc/CUTOVER_2026.md delete mode 100644 doc/INSTALL.md (limited to 'doc') diff --git a/doc/CUTOVER_2026.md b/doc/CUTOVER_2026.md new file mode 100644 index 00000000..2a6cb22a --- /dev/null +++ b/doc/CUTOVER_2026.md @@ -0,0 +1,348 @@ +# Rails 2 to Rails 8 cutover, June 2026 + +A historical record of one migration onto a fresh FreeBSD jail. NOT an +installation guide and no longer maintained: branch names, Ruby and +gemset versions, migration stamps and expected test counts are all +stale. See INSTALL.md for setting the project up. + +## CCCMS Installation Guide + +This document covers the non-obvious steps required to install the CCCMS +stack on a fresh FreeBSD jail. It assumes a FreeBSD 14.x base jail with +network access and a working pkg repository. + +## 1. Install packages + +```sh +pkg install gmake pkgconf curl gnupg git autoconf automake libtool bash \ + readline libyaml libffi gdbm libxml2 libxslt libical \ + postgresql16-server postgresql16-client \ + ImageMagick7-nox11 node vim +``` + +Note: the package is `ImageMagick7-nox11`, not `ImageMagick-nox11`. The +nox11 variant avoids pulling in the entire X11 dependency chain. + +## 2. Enable sysvipc for the jail + +PostgreSQL uses System V shared memory for inter-process communication. +On the host, the jail must have sysvipc enabled. In `/etc/jail.conf` or +the jail's ezjail configuration: + + `allow.sysvipc = 1;` + +Restart the jail after making this change. Without it, PostgreSQL will +fail to start with a shared memory error. + +## 3. Enable and initialise PostgreSQL + +```sh +# Enable PostgreSQL in rc.conf +echo 'postgresql_enable="YES"' >> /etc/rc.conf + +# Initialise the database cluster +service postgresql initdb + +# Start PostgreSQL +service postgresql start +``` + +## 4. Create database roles and set permissions + +```sh +psql -U postgres postgres +``` + +```sql +CREATE ROLE rails WITH LOGIN PASSWORD 'your-password-here'; +ALTER ROLE rails CREATEDB; +``` + +`CREATEDB` is required for the Rails test suite to create and drop the +test database between runs. + +## 5. Create databases + +```sql +CREATE DATABASE cccms_production OWNER rails ENCODING 'UTF8' + LC_COLLATE 'en_US.UTF-8' LC_CTYPE 'en_US.UTF-8' TEMPLATE template0; +CREATE DATABASE cccms_dev OWNER rails ENCODING 'UTF8' + LC_COLLATE 'en_US.UTF-8' LC_CTYPE 'en_US.UTF-8' TEMPLATE template0; +CREATE DATABASE psql_test OWNER rails ENCODING 'UTF8' + LC_COLLATE 'en_US.UTF-8' LC_CTYPE 'en_US.UTF-8' TEMPLATE template0; +``` + +`TEMPLATE template0` is required when specifying a non-default locale. + +## 6. Restore the database dump (or start empty) + +If restoring from a pg_dump: + +```sh +pg_restore -U postgres -d cccms_production \ + --no-owner --no-acl /path/to/cccms_production.dump + +pg_restore -U postgres -d cccms_dev \ + --no-owner --no-acl /path/to/cccms_production.dump +``` + +Expected harmless warnings: +- `schema "public" already exists` — benign, ignore +- `array_accum aggregate` failure — dead code, ignore + +Transfer ownership to the rails user (REASSIGN OWNED does not work on +PostgreSQL 15+ due to system object protection): + +```sh +psql -U postgres cccms_production +``` + +```sql +DO $$ +DECLARE + obj RECORD; +BEGIN + FOR obj IN + SELECT tablename FROM pg_tables WHERE schemaname = 'public' + LOOP + EXECUTE 'ALTER TABLE public.' || quote_ident(obj.tablename) || + ' OWNER TO rails'; + END LOOP; + FOR obj IN + SELECT sequence_name FROM information_schema.sequences + WHERE sequence_schema = 'public' + LOOP + EXECUTE 'ALTER SEQUENCE public.' || quote_ident(obj.sequence_name) || + ' OWNER TO rails'; + END LOOP; + FOR obj IN + SELECT viewname FROM pg_views WHERE schemaname = 'public' + LOOP + EXECUTE 'ALTER VIEW public.' || quote_ident(obj.viewname) || + ' OWNER TO rails'; + END LOOP; +END $$; + +ALTER SCHEMA public OWNER TO rails; +``` + +Repeat for `cccms_dev`. + +## 7. Clone the repository + +```sh +cd /usr/local/www +git clone https://github.com/erdgeist/cccms.git +cd cccms +git checkout rails-upgrade +``` + +## 8. Copy assets (optional but recommended) + +The `public/system/uploads/` directory contains all uploaded files +referenced by the database. Without it, images and attachments will be +missing throughout the site. + +```sh +# On the source system: +tar -czf /tmp/cccms_uploads.tar.gz -C /usr/local/www cccms/public/system + +# On the new system: +tar -xzf /path/to/cccms_uploads.tar.gz -C /usr/local/www +``` + +## 9. Copy gitignored config files + +These files are not in the repository and must be copied or created: + +```sh +# Required: +config/database.yml +config/initializers/secret_token.rb + +# If used: +config/initializers/exception_notification.rb +/usr/local/etc/unicorn.rb +``` + +`database.yml` template: + +```yaml +development: + adapter: postgresql + encoding: unicode + database: cccms_dev + pool: 5 + username: rails + password: your-password-here + +test: + adapter: postgresql + encoding: UTF8 + database: psql_test + username: rails + password: + +production: + adapter: postgresql + encoding: unicode + database: cccms_production + pool: 5 + username: rails + password: your-password-here +``` + +## 10. Install rvm + +rvm 1.29.12 is the latest formal release as of mid-2026. Download and +verify before installing: + +```sh +curl -L https://github.com/rvm/rvm/releases/download/1.29.12/1.29.12.tar.gz \ + -o /tmp/rvm-1.29.12.tar.gz +curl -L https://github.com/rvm/rvm/releases/download/1.29.12/1.29.12.tar.gz.asc \ + -o /tmp/rvm-1.29.12.tar.gz.asc + +gpg --keyserver hkps://keys.openpgp.org \ + --recv-keys 7D2BAF1CF37B13E2069D6956105BD0E739499BDB + +gpg --verify /tmp/rvm-1.29.12.tar.gz.asc /tmp/rvm-1.29.12.tar.gz +``` + +If verification passes: + +```sh +tar -xzf /tmp/rvm-1.29.12.tar.gz -C /tmp +bash /tmp/rvm-1.29.12/install --auto-dotfiles +source /usr/local/rvm/scripts/rvm +``` + +The installed rvm ships with a stale known-versions list that only goes +to Ruby 3.0.0. Update it immediately: + +```sh +curl -L https://raw.githubusercontent.com/rvm/rvm/master/config/known \ + -o /usr/local/rvm/config/known +rvm list known | grep '^\[ruby-\]3\.' +``` + +Should now show Ruby 3.2.x and later. + +## 11. Install Ruby and create gemset + +```sh +source /usr/local/rvm/scripts/rvm +rvm install 3.2.11 --autolibs=read-only --with-opt-dir=/usr/local +rvm use 3.2.11 +rvm gemset create rails7-upgrade +rvm use 3.2.11@rails7-upgrade +``` + +The `.ruby-version` and `.ruby-gemset` files in the project root will +cause rvm to switch automatically when entering the project directory. + +## 12. Install bundler and gems + +```sh +gem install bundler +cd /usr/local/www/cccms +export MAKE=gmake +bundle install 2>&1 | tee /tmp/bundle_install.log +``` + +`MAKE=gmake` is required because FreeBSD's native make (BSD make) uses +different `-j` syntax than native gems expect. Without it, several native +gem compilations will fail. + +## 13. Run migrations + +```sh +bundle exec rails db:migrate +``` + +If restoring an existing database, first insert fake migration versions +to prevent re-running migrations that were applied to the old schema: + +```sql +INSERT INTO schema_migrations (version) VALUES + ('20260624035149'), ('20260624035150'), ('20260624035151'), + ('20260624035152'), ('20260624035153'), + ('20260625031409') +ON CONFLICT DO NOTHING; +``` + +Then run `db:migrate` to apply only new migrations. + +To enable full-text search (requires PostgreSQL 10+ with plpgsql): + +```sh +mv doc/20260626025705_add_search_vector_to_page_translations.rb.pending \ + db/migrate/20260626025705_add_search_vector_to_page_translations.rb +bundle exec rails db:migrate +``` + +## 14. Compile admin assets + +```sh +bundle exec rails assets:precompile +``` + +This compiles the admin JavaScript bundle (jQuery, jQuery UI, hotkeys) +into `public/assets/`. Required for the admin interface to work. Must be +re-run after any changes to `app/assets/javascripts/admin_bundle.js`. + +## 15. Run tests (optional but recommended) + +```sh +bundle exec rake test +``` + +Expected result: 129 runs, ~339 assertions, 3 failures, 0 errors. +The 3 failures are pre-existing and documented in the handover document. + +## 16. Start the server + +Development: + +```sh +bundle exec rails server -p 3000 -b 0.0.0.0 -e development +``` + +Note: `-b 0.0.0.0` is required — `localhost` does not resolve inside +a FreeBSD jail. + +Production (unicorn): + +```sh +/usr/local/rvm/gems/ruby-3.2.11@rails7-upgrade/wrappers/unicorn \ + -c /usr/local/etc/unicorn.rb -E production -D +``` + +The rc.d script at `/etc/rc.d/cccms` needs updating from `unicorn_rails` +to `unicorn` before use — see the handover document for details. + +## Known Gotchas + +**sysvipc:** PostgreSQL will fail silently or with a cryptic error if +sysvipc is not enabled for the jail. Enable it on the host before starting +PostgreSQL. + +**MAKE=gmake:** Native gem compilation fails without this. Set it before +every `bundle install` or add to your shell profile. + +**rvm known versions:** rvm 1.29.12 ships with a stale `config/known` that +only lists Ruby up to 3.0.0. Always update from master after installing rvm. + +**ImageMagick 7:** The `convert` command is deprecated; use `magick convert`. +The `file_attachment.rb` concern needs updating before production use. + +**pg_hba.conf:** The default FreeBSD PostgreSQL configuration uses `trust` +for local Unix socket connections, which is sufficient for the application. +No changes needed unless TCP connections are required. + +**assets:precompile:** Must be run after checkout and after any changes to +admin JavaScript. The compiled files in `public/assets/` are gitignored. + +**chaos_calendar include path:** On FreeBSD 14.x with libical 3.0.20+, +the include path is `` not ``. This is already +fixed in the `erdgeist-ruby1.9` branch. diff --git a/doc/INSTALL.md b/doc/INSTALL.md deleted file mode 100644 index 8056f7cf..00000000 --- a/doc/INSTALL.md +++ /dev/null @@ -1,341 +0,0 @@ -# CCCMS Installation Guide - -This document covers the non-obvious steps required to install the CCCMS -stack on a fresh FreeBSD jail. It assumes a FreeBSD 14.x base jail with -network access and a working pkg repository. - -## 1. Install packages - -```sh -pkg install gmake pkgconf curl gnupg git autoconf automake libtool bash \ - readline libyaml libffi gdbm libxml2 libxslt libical \ - postgresql16-server postgresql16-client \ - ImageMagick7-nox11 node vim -``` - -Note: the package is `ImageMagick7-nox11`, not `ImageMagick-nox11`. The -nox11 variant avoids pulling in the entire X11 dependency chain. - -## 2. Enable sysvipc for the jail - -PostgreSQL uses System V shared memory for inter-process communication. -On the host, the jail must have sysvipc enabled. In `/etc/jail.conf` or -the jail's ezjail configuration: - - `allow.sysvipc = 1;` - -Restart the jail after making this change. Without it, PostgreSQL will -fail to start with a shared memory error. - -## 3. Enable and initialise PostgreSQL - -```sh -# Enable PostgreSQL in rc.conf -echo 'postgresql_enable="YES"' >> /etc/rc.conf - -# Initialise the database cluster -service postgresql initdb - -# Start PostgreSQL -service postgresql start -``` - -## 4. Create database roles and set permissions - -```sh -psql -U postgres postgres -``` - -```sql -CREATE ROLE rails WITH LOGIN PASSWORD 'your-password-here'; -ALTER ROLE rails CREATEDB; -``` - -`CREATEDB` is required for the Rails test suite to create and drop the -test database between runs. - -## 5. Create databases - -```sql -CREATE DATABASE cccms_production OWNER rails ENCODING 'UTF8' - LC_COLLATE 'en_US.UTF-8' LC_CTYPE 'en_US.UTF-8' TEMPLATE template0; -CREATE DATABASE cccms_dev OWNER rails ENCODING 'UTF8' - LC_COLLATE 'en_US.UTF-8' LC_CTYPE 'en_US.UTF-8' TEMPLATE template0; -CREATE DATABASE psql_test OWNER rails ENCODING 'UTF8' - LC_COLLATE 'en_US.UTF-8' LC_CTYPE 'en_US.UTF-8' TEMPLATE template0; -``` - -`TEMPLATE template0` is required when specifying a non-default locale. - -## 6. Restore the database dump (or start empty) - -If restoring from a pg_dump: - -```sh -pg_restore -U postgres -d cccms_production \ - --no-owner --no-acl /path/to/cccms_production.dump - -pg_restore -U postgres -d cccms_dev \ - --no-owner --no-acl /path/to/cccms_production.dump -``` - -Expected harmless warnings: -- `schema "public" already exists` — benign, ignore -- `array_accum aggregate` failure — dead code, ignore - -Transfer ownership to the rails user (REASSIGN OWNED does not work on -PostgreSQL 15+ due to system object protection): - -```sh -psql -U postgres cccms_production -``` - -```sql -DO $$ -DECLARE - obj RECORD; -BEGIN - FOR obj IN - SELECT tablename FROM pg_tables WHERE schemaname = 'public' - LOOP - EXECUTE 'ALTER TABLE public.' || quote_ident(obj.tablename) || - ' OWNER TO rails'; - END LOOP; - FOR obj IN - SELECT sequence_name FROM information_schema.sequences - WHERE sequence_schema = 'public' - LOOP - EXECUTE 'ALTER SEQUENCE public.' || quote_ident(obj.sequence_name) || - ' OWNER TO rails'; - END LOOP; - FOR obj IN - SELECT viewname FROM pg_views WHERE schemaname = 'public' - LOOP - EXECUTE 'ALTER VIEW public.' || quote_ident(obj.viewname) || - ' OWNER TO rails'; - END LOOP; -END $$; - -ALTER SCHEMA public OWNER TO rails; -``` - -Repeat for `cccms_dev`. - -## 7. Clone the repository - -```sh -cd /usr/local/www -git clone https://github.com/erdgeist/cccms.git -cd cccms -git checkout rails-upgrade -``` - -## 8. Copy assets (optional but recommended) - -The `public/system/uploads/` directory contains all uploaded files -referenced by the database. Without it, images and attachments will be -missing throughout the site. - -```sh -# On the source system: -tar -czf /tmp/cccms_uploads.tar.gz -C /usr/local/www cccms/public/system - -# On the new system: -tar -xzf /path/to/cccms_uploads.tar.gz -C /usr/local/www -``` - -## 9. Copy gitignored config files - -These files are not in the repository and must be copied or created: - -```sh -# Required: -config/database.yml -config/initializers/secret_token.rb - -# If used: -config/initializers/exception_notification.rb -/usr/local/etc/unicorn.rb -``` - -`database.yml` template: - -```yaml -development: - adapter: postgresql - encoding: unicode - database: cccms_dev - pool: 5 - username: rails - password: your-password-here - -test: - adapter: postgresql - encoding: UTF8 - database: psql_test - username: rails - password: - -production: - adapter: postgresql - encoding: unicode - database: cccms_production - pool: 5 - username: rails - password: your-password-here -``` - -## 10. Install rvm - -rvm 1.29.12 is the latest formal release as of mid-2026. Download and -verify before installing: - -```sh -curl -L https://github.com/rvm/rvm/releases/download/1.29.12/1.29.12.tar.gz \ - -o /tmp/rvm-1.29.12.tar.gz -curl -L https://github.com/rvm/rvm/releases/download/1.29.12/1.29.12.tar.gz.asc \ - -o /tmp/rvm-1.29.12.tar.gz.asc - -gpg --keyserver hkps://keys.openpgp.org \ - --recv-keys 7D2BAF1CF37B13E2069D6956105BD0E739499BDB - -gpg --verify /tmp/rvm-1.29.12.tar.gz.asc /tmp/rvm-1.29.12.tar.gz -``` - -If verification passes: - -```sh -tar -xzf /tmp/rvm-1.29.12.tar.gz -C /tmp -bash /tmp/rvm-1.29.12/install --auto-dotfiles -source /usr/local/rvm/scripts/rvm -``` - -The installed rvm ships with a stale known-versions list that only goes -to Ruby 3.0.0. Update it immediately: - -```sh -curl -L https://raw.githubusercontent.com/rvm/rvm/master/config/known \ - -o /usr/local/rvm/config/known -rvm list known | grep '^\[ruby-\]3\.' -``` - -Should now show Ruby 3.2.x and later. - -## 11. Install Ruby and create gemset - -```sh -source /usr/local/rvm/scripts/rvm -rvm install 3.2.11 --autolibs=read-only --with-opt-dir=/usr/local -rvm use 3.2.11 -rvm gemset create rails7-upgrade -rvm use 3.2.11@rails7-upgrade -``` - -The `.ruby-version` and `.ruby-gemset` files in the project root will -cause rvm to switch automatically when entering the project directory. - -## 12. Install bundler and gems - -```sh -gem install bundler -cd /usr/local/www/cccms -export MAKE=gmake -bundle install 2>&1 | tee /tmp/bundle_install.log -``` - -`MAKE=gmake` is required because FreeBSD's native make (BSD make) uses -different `-j` syntax than native gems expect. Without it, several native -gem compilations will fail. - -## 13. Run migrations - -```sh -bundle exec rails db:migrate -``` - -If restoring an existing database, first insert fake migration versions -to prevent re-running migrations that were applied to the old schema: - -```sql -INSERT INTO schema_migrations (version) VALUES - ('20260624035149'), ('20260624035150'), ('20260624035151'), - ('20260624035152'), ('20260624035153'), - ('20260625031409') -ON CONFLICT DO NOTHING; -``` - -Then run `db:migrate` to apply only new migrations. - -To enable full-text search (requires PostgreSQL 10+ with plpgsql): - -```sh -mv doc/20260626025705_add_search_vector_to_page_translations.rb.pending \ - db/migrate/20260626025705_add_search_vector_to_page_translations.rb -bundle exec rails db:migrate -``` - -## 14. Compile admin assets - -```sh -bundle exec rails assets:precompile -``` - -This compiles the admin JavaScript bundle (jQuery, jQuery UI, hotkeys) -into `public/assets/`. Required for the admin interface to work. Must be -re-run after any changes to `app/assets/javascripts/admin_bundle.js`. - -## 15. Run tests (optional but recommended) - -```sh -bundle exec rake test -``` - -Expected result: 129 runs, ~339 assertions, 3 failures, 0 errors. -The 3 failures are pre-existing and documented in the handover document. - -## 16. Start the server - -Development: - -```sh -bundle exec rails server -p 3000 -b 0.0.0.0 -e development -``` - -Note: `-b 0.0.0.0` is required — `localhost` does not resolve inside -a FreeBSD jail. - -Production (unicorn): - -```sh -/usr/local/rvm/gems/ruby-3.2.11@rails7-upgrade/wrappers/unicorn \ - -c /usr/local/etc/unicorn.rb -E production -D -``` - -The rc.d script at `/etc/rc.d/cccms` needs updating from `unicorn_rails` -to `unicorn` before use — see the handover document for details. - -## Known Gotchas - -**sysvipc:** PostgreSQL will fail silently or with a cryptic error if -sysvipc is not enabled for the jail. Enable it on the host before starting -PostgreSQL. - -**MAKE=gmake:** Native gem compilation fails without this. Set it before -every `bundle install` or add to your shell profile. - -**rvm known versions:** rvm 1.29.12 ships with a stale `config/known` that -only lists Ruby up to 3.0.0. Always update from master after installing rvm. - -**ImageMagick 7:** The `convert` command is deprecated; use `magick convert`. -The `file_attachment.rb` concern needs updating before production use. - -**pg_hba.conf:** The default FreeBSD PostgreSQL configuration uses `trust` -for local Unix socket connections, which is sufficient for the application. -No changes needed unless TCP connections are required. - -**assets:precompile:** Must be run after checkout and after any changes to -admin JavaScript. The compiled files in `public/assets/` are gitignored. - -**chaos_calendar include path:** On FreeBSD 14.x with libical 3.0.20+, -the include path is `` not ``. This is already -fixed in the `erdgeist-ruby1.9` branch. -- cgit v1.3