Filonio — installation guide (English summary)

Filonio redesigns the Redmine interface without touching Redmine's core. It ships as two archives of the same version: the theme (filonio-theme-<version>.zip) and the companion plugin (filonio-plugin-<version>.zip). Without the plugin, the theme is inactive: only the plugin turns Filonio on, and only while the trial or the licence is valid. Otherwise Redmine keeps its original interface, with no data loss. The French documentation in docs/ is the reference; this page summarises installation, licence, upgrade, removal and troubleshooting.

Requirements

Redmine 5.1.x to 7.0 (reference version: 6.1; 5.1.x, 6.0 and 7.0 are being validated). The plugin refuses to start below 5.1.0; above the last checked branch (7.0) it stays active and warns administrators.
Ruby of your Redmine version. The licence is an Ed25519-signed token: with Ruby 3.1 or later, nothing to add; with Ruby 2.7 to 3.0, the ed25519 gem is required, compiled by bundle install in the Redmine folder (C build tools needed, e.g. build-essential).
Chrome / Edge 120+, Firefox 121+, Safari 17+. Checked at 1440, 1024, 768 and 390 px wide (tablet drawers below 1280 px, bottom tab bar and card lists below 640 px).
Shell access to run bundle exec rake and restart Redmine; outbound HTTPS to the licence server. Back up the database and the Redmine folder first.

Install

cd /path/to/redmine
unzip filonio-theme-0.1.0.zip -d themes/          # Redmine 6.x and 7.0
unzip filonio-theme-0.1.0.zip -d public/themes/   # Redmine 5.1.x
unzip filonio-plugin-0.1.0.zip -d plugins/
bundle install                                     # plugin dependencies (ed25519 gem on Ruby 2.7 to 3.0)
bundle exec rake redmine:plugins:migrate RAILS_ENV=production

Without unzip, python3 -m zipfile -e filonio-theme-0.1.0.zip themes/ does the same. Restart Redmine (docker compose restart redmine, touch tmp/restart.txt with Passenger, or your service manager). On Redmine 6.x and 7.0, theme assets are recompiled at startup when a change is detected; if config.assets.redmine_detect_update is disabled, run bundle exec rake assets:precompile RAILS_ENV=production first.

Select the theme in Administration › Settings › Display › Theme, or:

bundle exec rails runner -e production 'Setting.ui_theme = "filonio"'

With the official Redmine Docker image, rails runner and rake run through docker compose exec need SECRET_KEY_BASE (or REDMINE_SECRET_KEY_BASE) in the container environment, like the server itself.

The first page displayed after that contacts the licence server (2 seconds at most) and starts a 14-day trial. If the server cannot be reached, Redmine keeps its original interface, administrators see a "Filonio is not activated yet" dialog, and the plugin retries one hour later.

Check: bundle exec rails runner -e production 'p Redmine::Plugin.find(:filonio).version' prints the version; bundle exec rake filonio:license:status RAILS_ENV=production prints the licence state; the page source starts with <html data-filonio="on" …> when Filonio is active (data-filonio="off": theme selected but licence not valid or incompatible versions; no attribute: plugin missing).

Theme and plugin must have the same version. A different major version switches Filonio off and warns administrators on every page; a different minor or patch version (or a missing theme VERSION file) only warns them on the administration pages, where the licence page also shows a "Compatibility" row.

Licence

Administration › Filonio licence shows the trial or licence state and lets you activate a key. A paid licence covers one production instance (and one test instance) with no user limit and includes 12 months of updates and support (updates_until in the token). After 12 months, Filonio keeps working in the last version received; renewing reopens updates and support. A version released after the end of your updates turns itself off (banner to administrators) until you renew or reinstall an earlier version. A lapsed licence no longer needs the licence server.

The trial ends at expires_at, followed by a 7-day grace period. When the licence server is unreachable during the trial or the paid period, the cached token stays valid until valid_until (offline validity), then a 7-day grace period starts. After the grace period (or immediately on revocation), Redmine falls back to its original interface with no data loss, and administrators see a dialog to activate a licence. Banners (trial days left, grace period, unreachable server, end of updates) are shown to administrators only.

Technical causes (storage: plugin tables missing; token_unsupported: Ed25519 unavailable on this Ruby; clock: server clock set back) do not switch the theme off: administrators see a "Filonio licence cannot be checked" banner with the cause and the fix.

The plugin contacts the Filonio licence server over HTTPS about every 12 hours: it is the only outbound flow to allow. Schedule bundle exec rake filonio:license:heartbeat RAILS_ENV=production (e.g. every 6 hours; exit code 1 when the exchange fails). On a copy of a production database, delete the filonio_license_states row so the copy gets its own instance fingerprint (bundle exec rails runner -e production 'FilonioLicenseState.delete_all'). An instance without outbound access is activated with a signed token: send its fingerprint (same page) to [email protected].

Issue board

The plugin adds a Board tab (between List and Calendar) on project and global issue lists: one column per status, same filters and saved queries as the list, 50 cards per column with a link to the rest. Moving a card (drag and drop from 640 px wide, or the "Move to…" menu, keyboard included) changes the issue status through Redmine itself (journal, workflow, notifications). Viewing requires View issues; moving requires Edit issues or Edit own issues and a workflow transition. An expired session shows "Session expired: sign in again, then retry." with a sign-in button. See Tableau des demandes for refusal codes.

Third-party plugins

Two plugins have dedicated styling (allow-list in the plugin settings, all checked by default): Plio (workload planning) and redmine_more_previews. Other plugins keep a neutral base: the theme's colours, typography and components applied to the core markup they reuse.

Upgrade

Remove themes/filonio (Redmine 5.1.x: public/themes/filonio) and plugins/filonio, unzip the new archives, run bundle install and the plugin migrations, restart Redmine. Theme and plugin must always have the same version.

Compact density by default (releases after 0.1.0). Users who have not chosen a density switch to Compact (40 px list rows, 28 px controls, 13 px text). No migration: choices saved in My account are kept. If the Administration › Plugins › Filonio › Configure page was saved before, it stored Comfortable, which stays the instance default: pick Compact and save to adopt it, or keep Comfortable.

Remove

bundle exec rails runner -e production 'Setting.ui_theme = ""'
bundle exec rake redmine:plugins:migrate NAME=filonio VERSION=0 RAILS_ENV=production
rm -rf plugins/filonio themes/filonio             # Redmine 5.1.x: public/themes/filonio

Restart Redmine. Issues, projects and wiki are untouched; user appearance preferences (filonio_* keys) and plugin settings stay in the database without effect (see Désinstallation for database-independent purge commands).

Troubleshooting

Theme CSS / JS returns 404 after an upgrade: restart Redmine; otherwise bundle exec rake assets:precompile RAILS_ENV=production (or assets:clobber assets:precompile), then restart.
Theme not listed: the folder must be themes/filonio (Redmine 5.1.x: public/themes/filonio); restart Redmine.
Original interface shown: check the data-filonio attribute (see above), the licence page and that theme and plugin versions match.
Page header missing for a second: the theme script did not load (CSP, proxy, 404); the original Redmine header shows after less than one second.
Requests to gravatar.com: Redmine's avatar setting, not Filonio.

Copy of the documentation shipped with Filonio (docs/ folder of the archives).