Free Open-Source participatory democracy, citizen participation and open government for Berlin and its organizations. This is the open-source repository for decidim_berlin, based on Decidim.
You will need to do some steps before having the app working properly on your machine:
- Open a Rails console in the server:
bundle exec rails console - Create a System Admin user:
Decidim::System::Admin.create!(email: <email>, password: <password>, password_confirmation: <password>)- Visit
<your app url>/systemand login with your system admin credentials - Create a new organization. Check the locales you want to use for that organization, and select a default locale.
- Set the correct default host for the organization, otherwise the app will not work properly. Note that you need to include any subdomain you might be using.
- Fill the rest of the form and submit it.
You're good to go!
Locally you can also use the provided seeds, but they seem to be a bit flaky. Just try bin/rails db:seed again a couple of times if they fail.
If you use the seeds you can:
- Browse the main interface at http://localhost:3000, and log in as: [email protected] | decidim123456
- Browse the admin interface at http://localhost:3000/admin, and log in as: [email protected] | decidim123456
- Browse the system interface at http://localhost:3000/system, and log in as: [email protected] | decidim123456
Possible modules are listed at https://github.com/decidim/decidim. Find the one you need, click on the link and follow the instructions in your development environment. If everything checks out commit your changes and start the deployment as described below.
We use Capistrano for deployment.
You can run bundle exec cap production deploy to trigger the deployment process in the app folder.
For this to work you need an ssh key that is both registered with the server you're deploying to and have access to the repository on github.
Capistrano will then:
- Ssh into the server
- Checkout github's master branch in the
releases-folder - Ensure all necessary gems are installed with
bundle install - Run pending migrations
- Compile the assets if necessary
- Link files and directories that should be shared between releases (like the
database.yml) - Link
/home/decidim/current(which is targeted by the nginx-passenger) to the new release - Restart nginx-passenger to ensure the new release is used
If something goes wrong use cap production deploy:rollback to link current to the folder of the previous release. Capistrano keeps the last 5 releases.
At the time of this writing there are two installation manuals mentioned on the github repository for decidim:
-
The official installation manual at
https://github.com/decidim/decidim/blob/master/docs/manual-installation.md -
An inofficial installation manual at
https://github.com/Platoniq/decidim-install/blob/master/decidim-focal.mdwith it's follow-up "basic configuration" (https://github.com/Platoniq/decidim-install/blob/master/basic-config.md)
The inofficial manual has a lot more detail and is recommended for people not experienced with Rails and for people that don't have a server set up yet on which they want to run decidim. The only outdated part of this guide is about using the gem figaro. Decidim currently uses Rails >= 5.2. which supports "Rails Credentials", which makes figaro obsolete. See https://developer.epages.com/blog/coding/no-more-hassle-with-rails-secret-management.
While the unofficial guide is very detailed and aims to get you going from nothing to a running decidim instance there is also no guide for setting up your domain and its DNS records. You can use gandi as a registrar and their tutorial for example.
The official manual is heavily outdated but is more focussed on decidim so it can be helpful if you have specific requirements for your infrastructure. If you're not entirely sure we heavily recommend not following the official installation instructions and follow the unofficial one instead.
One thing we found unintuitive are the different user types. So here's a little overview to reduce confusion. There are:
-
System admins (also called super admins) These are admins that can manage your installation instance, organizations and should have technical knowledge. You'll probably won't need more than one or two of those. Possibly those that set up the instance. So you - the reader - probably ;-) You'll likely don't need to talk about this role with non-technical users. The url to login as a system admin is:
https://<domain>/system/admins/sign_in -
Organization admins (which is a user with the admin flag, that belongs to an organization) These are admins of one organization (You can think of an organization as a group of people that want to make decisions together, an organization always has a unique host). Organization admins don't need a technical background. They can set up modules/processes/conferences/... and are exposed to all of the core features of decidim. Organization admins need to understand what decidim is about, what it can do, and how to do it. The admin-manual is a good place to get familiar with decidim as an admin even though it's from 2018. The url to log in as an organization admin is:
https://<organization-host>/users/sign_in -
Organization users which take part in the decision making process. The interface is supposed to be as self-explanatory as possible, but expect people to need support from admins. They url to log in as organization admins:
https://<organization-host>/users/sign_in.
Take note that the organization-host and the domain can be the same. The organization host is either the <domain> or <subdomain>.<domain>. That means that a common setup for manual checks would be to have three accounts:
<domain>/system/admins/sign_into sign in as a system admin (and configure organizations).<domain>/users/sign_inwith an admin account to test as an organization admin. The documentation mentionshttps://decidim.de/admin, but the request is redirected to<domain>/users/sign_in.<domain>/users/sign_inwith a different user account to test as an organization user.
What's missing in both guides is a way to modify and deploy customizations. There is a part called "Going pro (optional):" in the unofficial guide, which sets up a git repository for your decidim instance. We heavily recommend following it, but it still assumes all changes are made on the (production) server directly. If you want to have more safety while customizing (or updating) your decidim instance (including translations, see below), we recommend setting up Capistrano for deployment so you can change code locally before your production site is effected. Docker is an alternative as well, but the official guide marks the docker setup as "experimental", so if you prefer that you probably shouldn't need this guide anyway.
Decidim translations are community-sourced with crowdin, but the state of german decidim translations is unintuitive at best and confusing at worst. Some similar but different concepts have the same name, other translations sound weird and even others seem to have been defined for a specific use case in mind that didn't fit our case and possibly won't fit yours. Especially because of the last issue and possibly long-term discussions associated with it we decided to customize translations for our use cases.
To do that you can create a translation file called z9_custom.yml in config/locales. z9... so that it's loaded last thus overwriting tranlsations from previous files. We included the translations used by decidim grouped by modules in our app's translations so it's easier to find the keys for translations you want to change. This way you can see a snippet of text on your decidim page, search for it in the translation files, look for the key, add the key to your z9_custom.yml and add the text you want to see instead. Feel free to copy the extracted translation files from https://github.com/decidim-de/decidim_berlin/tree/master/config/locales for your setup as well.
Gems are ruby's libraries - other people's code that we incorporate into our codebase. Ruby is an interpreted language so most of the gems are just the source code copied to a folder on the machine running the app. Ruby comes with a gem command (rubygems), that allows to install gems on your machine.
Bundler is the standard dependency manager for ruby. People have been thinking about incorporating bundler into rubygems, but that hasn't happened yet. So for now bundler is a gem that manages gem dependencies and builds a "bundle" of gems that work for your app. For standard rails app bundler is the only gem that is installed with rubygems directly. After bundler is installed rubygems will usually only be invoked only by bundler when you run bundle install. There are two files that bundler uses for two different purposes.
Gemfile is where we define the gems we want for our app and allows bundler to find fitting versions for them. Gemfile.lock is where bundler stores these fitting versions using the newest available gems at the time of running bundler and the limitiations defined in Gemfile.
In Gemfile we can set a maximum and minimum for the allowed versions of any gem, or define the version exactly. We can also set gems to be used only for a specific environment. For example is it unnecessary for our production instance to install any gems we use only for testing. Bundler will use Gemfile to find compatible versions for all the specified gems stop execution if it can't. An example: The newest version of gem a depends on gem b with exactly version 1.12, the newest version of gem c depends on gem b with version greater than 1.14. We have gem a and gem c in our gemfile. Bundler can't find a version of gem b that satisfies our requirements. So it stops and tells us. We can than set specific versions for gem a and gem c that have other requirements for versions to resolve the version conflict.
Using Gemfile.lock allows to avoid surprises coming from different gem versions on different machines. If we run bundler with an existing Gemfile.lock on two different machines it will fetch exactly the same versions defined by Gemfile.lock. So production and all our development machines will have exactly the same gem code. To have bundler look for the newest version of a gem again run bundle update <gemname>. This will adhere to the limitations in Gemfile and update Gemfile.lock.
The exception to gems that are just copied source code are gems that use C bindings or extensions. Ruby allows this to have a way to deal with very performance-critical tasks and some gems make use of that. That means that sometimes during gem installation you will see a message that "native extensions" are being "built". Installing these gems takes a lot longer due to this extra compilation step and may require C-libraries that you might need to install on your system. Homebrew is often recommended on MAC for doing this. On Linux the distro's package manager is usually the best choice. Installing nokogiri (ruby's most widely used XML-parser) is the most common case rubyist have to deal with C-libraries. Read the error messages very carefully. Often they state the missing libraries. If that doesn't help googling the error message will usually lead to good information.
Gems play a more important role for this app than in most other Rails apps, because all (maybe this will be "most" in the future) of our views and the database structure rely on the decidim gems.
See https://bundler.io and https://guides.rubygems.org/rubygems-basics for more information.