1 files changed, 341 insertions, 0 deletions

diff --git a/doc/INSTALL.md b/doc/INSTALL.md
new file mode 100644
index 0000000..8056f7c
--- /dev/null
+++ b/doc/INSTALL.md
@@ -0,0 +1,341 @@
+# 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 `<libical/ical.h>` not `<ical.h>`. This is already
+fixed in the `erdgeist-ruby1.9` branch.