Adds documentation for manual installation on Ubuntu LTS 16.04 by andreslucena · Pull Request #2887 · decidim/decidim

andreslucena · 2018-03-02T14:10:41Z

Instructions for:

rbenv
PostgreSQL
git
figaro

🎩 What? Why?

There are some newcommers to the project that don't understand that well the manual installation instructions. This tries to fix that and also show some good practices on Ruby on Rails development (ie using git, figaro, etc).

📌 Related Issues

None

📋 Subtasks

None

📷 Screenshots (optional)

None

Instructions for: * rbenv * PostgreSQL * git * figaro

andreslucena · 2018-03-02T14:12:43Z

docs/manual-installation.md

+git commit -m "Adds figaro configuration management"
+```
+
+### Initializing your app for local development


Maybe here we should link to this section on getting started, so we don't duplicate the text, but the idea here was to be able to explain more what and where exactly you can log in and what can do every user.

mrcasals · 2018-03-02T14:14:26Z

docs/manual-installation.md

+
+## Step by step
+
+We're starting with an Ubuntu 16.04 LTS. This is an opinionated guy and YMMV, so if you're free to use the technology that you fell most comfortable on. If you have any doubts and you're blocked you can go and ask on [our Gitter](https://gitter.im/decidim/decidim). We recommend that you follow some Ruby on Rails tutorials (like [Getting Started with Ruby on Rails](http://guides.rubyonrails.org/getting_started.html)) and have some knowledge on how gems and engines work.


s/guy/guide/?

andreslucena · 2018-03-02T14:17:13Z

docs/manual-installation.md

+
+```bash
+git init .
+git commit -m "Initial commit. Generated with Decidim 0.X https://decidim.org"


Add something like "Where Decidim 0.X is your Decidim version (see your Gemfile)"

We can add this to the generator, it's cool! :)

mrcasals · 2018-03-02T14:20:50Z

I feel like we should direct the newcomers to some other official guide on how to setup their environment, outside our repo, instead of offering the guide ourselves. Otherwise we'll end up adding guides on how to install the environment in Mac & Windows too, and we'll have to keep them up to date.

Also, what is figaro and why is it needed to start developing with Decidim? I certainly have never used it 😕

deivid-rodriguez · 2018-03-02T14:50:14Z

docs/manual-installation.md

+```bash
+decidim decidim_application
+cd decidim_application
+bundle install


I think our generator automatically runs bundle install on the generated application.

deivid-rodriguez · 2018-03-02T14:53:36Z

docs/manual-installation.md

+
+```bash
+git add .
+git commit -m "Adds figaro configuration management"


Modern rails provide encrypted secrets out of the box now, maybe we should explore that so these tweaks are not necessary.

Ok, I forgot that was the Rails official way now. I've really didn't use it yet, the idea here was only to show the gist of handling secrets. I'll add a comment and link on a guide on using/handling the secrets.

Added the comment regarding secrets. As I said, I didn't try it (yet), although I've read that on 5.1 was secrets and now on 5.2 is call credentials, so I think it's still moving. After I try and test it on staging/production I'll update this.

@deivid-rodriguez we use rails-secrets and figaro in our projects but we use them differently, maybe we're doing it the wrong way:

rails-secrets only for data that can go to version control

figaro for data that can not be checked into version control.

Not sure, the idea in modern rails versions in that everything is checked into version control, but secret data is commited encrypted.

deivid-rodriguez · 2018-03-02T14:54:23Z

docs/manual-installation.md

+Now we're going to install PostgreSQL for the database:
+
+```bash
+sudo apt-get install -y postgresql libpq-dev


If libpq-dev is not installed, the previous bundle install will fail so probably this step should be before the generation of the application...

You can do this with a oneliner :)

sudo -u postgres psql -c "CREATE USER decidim_app WITH SUPERUSER CREATEDB NOCREATEROLE PASSWORD 'decidim_app'"

Not that I used NOCREATEROLE because the DB user does not need role creation privileges.

Ok, great feedback, I'll change it

If libpq-dev is not installed, the previous bundle install will fail so probably this step should be before the generation of the application...

I've moved the postgres installation so it's before decidim installation

You can do this with a oneliner :)

Changed it!

deivid-rodriguez · 2018-03-02T14:58:29Z

I kind of share a similar feeling to @mrcasals as to where these docs should live, but if @andreslucena is committed to maintaining these docs up to date, it could be a useful resource for newcomers...

andreslucena · 2018-03-09T10:06:07Z

Regarding figaro, it's just an example on how to handle secrets. I'll add other proposed alternatives, just so it's clear that it could be done on others ways.

Regarding if we should/shouldn't have this kind of documentation, please see https://consul_docs.gitbooks.io/docs/content/en/getting_started/prerequisites/linux.html - also check all the manual, I think it's much better and with much detail documentation than ours.

xabier · 2018-03-20T20:03:27Z

@mrcasals

I feel like we should direct the newcomers to some other official guide on how to setup their environment, outside our repo, instead of offering the guide ourselves. Otherwise we'll end up adding guides on how to install the environment in Mac & Windows too, and we'll have to keep them up to date.

It is very important for the democratic nature of the project to make it easy to install on GNU/Linux (not so much on Mac or Win, not really that many servers running win or mac). And I think it is very convenient to have the instructions included here, particularly if they are just a couple of command line options (or 7 for the same matter). We should hope for something like this: https://github.com/discourse/discourse/blob/master/docs/INSTALL-cloud.md

I know many organizations with competent admin who could not install Decidim. The more help we provide and clearer instructions the better. Not all environment installs work equal, and it is good to provide the way it works.

deivid-rodriguez · 2018-04-09T13:37:07Z

@xabier I agree that we need better setup/deployment docs, but I think @mrcasals had a good point here. If your read the patch, these are not 7 commands, but a recipe that can get quite complex, get outdated or change over time.

In my opinion discourse is indeed a fantastic model to follow because it satisfies both concerns:

It has nice, concise and clear setup instructions.
It uses a docker image so setting up ruby, postgresql and other global dependencies is completely transparent to the user since it's included in the image. And it works on any platform, so we won't need any platform specific stuff.

@josepjaume's input is very valuable here since I suspect he knows a lot about deploying docker images :)

andreslucena · 2018-04-10T15:28:02Z

@deivid-rodriguez I'm with you regarding that we should have something similar to what Discourse offers (or something that at least doesn't have that much steps as the instructions on this PR). Also this is going to be needed for another kind of applications that we want to integrate to (ie see #3166 )

This PR is only a set of instructions that wants to bridge the gap of what @xabier said:

I know many organizations with competent admin who could not install Decidim.

mrcasals · 2018-04-11T07:47:12Z

I don't use Ubuntu, so I can't commit to keep this updated, that's why I still think that all the part on how to install Ruby should be delegated to somewhere else... Maybe pointing to the rbenv/rvm docs page could be enough.

…id-rodriguez

…id-rodriguez * Change typo on guy/guide * PostgreSQL installation before installing Decidim * Removing bundle install on Decidim installation * Adds sekrets/encrypted secrets mention on secrets handling * Change postgreSQL database/user creation

codecov · 2018-04-12T14:44:52Z

Codecov Report

❗ No coverage uploaded for pull request base (master@a65219f). Click here to learn what that means.
The diff coverage is n/a.

@@            Coverage Diff            @@
##             master    #2887   +/-   ##
=========================================
  Coverage          ?   98.72%           
=========================================
  Files             ?     1651           
  Lines             ?    39195           
  Branches          ?        0           
=========================================
  Hits              ?    38697           
  Misses            ?      498           
  Partials          ?        0

andreslucena · 2018-04-20T08:33:35Z

I don't use Ubuntu, so I can't commit to keep this updated, that's why I still think that all the part on how to install Ruby should be delegated to somewhere else... Maybe pointing to the rbenv/rvm docs page could be enough.

The general idea of this guide is about downgrading the knowledge to at least install Decidim locally, by an Ubuntu sysadmin/user. I think the full instructions is important, although I also added a mention to RVM as an alternative.

andreslucena · 2018-04-20T08:38:22Z

In my opinion discourse is indeed a fantastic model to follow because it satisfies both concerns

Yes, we have that on the roadmap, this is just a quick patch on the doc side until we have something working on this area.

Discourse model seems like a good candidate for this problem, although there are some important differences with what Decidim is at the moment: for instance, Discourse is a full blown app (ie you can modify CSS/HTML/JS through the admin panel) and Decidim is a framework where you work directly with the Ruby on Rails application. Maybe the decidim-launcher would also need to point to a generated app?

We hope to talk about this (Decidim installation/development/deployment flows) on the near future.

andreslucena · 2018-04-24T08:51:29Z

I think that all the doubts/changes that were discussed are already responded or changed. @deivid-rodriguez @mrcasals could you say something and merge (or give more feedback)? Thanks!

deivid-rodriguez

@andreslucena I left some more feedback but it looks almost ready to me! I'm still afraid this will get outdated and get misleading instead of useful but I'm happy to be proven wrong!

deivid-rodriguez · 2018-04-24T10:45:17Z

docs/manual-installation.md

+gem install decidim
+```
+
+Afterwards, we can create an application with the nice `decidim` executable, where `decidim_application` is your application name (ie DecidimBarcelona):


Camelizing is a bit weird here I think, maybe decidim.barcelona is better.

deivid-rodriguez · 2018-04-24T10:52:54Z

docs/manual-installation.md

+rbenv global 2.5.0
+echo "gem: --no-document" > ~/.gemrc
+gem install bundler
+```


This still looks too specific to me... For example, it's already outdated and it's now recommending an potentially insecure ruby version without all the latest security patches (2.5.1 is out).

I would probably remove these instructions and mention that you need an up to date ruby and point out to official docs on installing it (or maybe even to our docker image).

But if we want to keep it in the repo we need to commit to keeping it up to date, so we should get that version updated.

andreslucena · 2018-05-07T08:34:45Z

@deivid-rodriguez I agree with all your comments regarding the short live of this doc, specially regarding software versions, ie Ubuntu LTS now is 18.04 😅

We hope to have a better installation/deployment method with @gmarpons - probably something based on Discourse scripts or something like that. If you know any other RoR open source projects that have a nice installation/deploy method that'd be awesome.

deivid-rodriguez

Ok, let's add this an iterate on better solutions later!

@mrcasals

…im#2887) * Adds documentation for manual installation on Ubuntu LTS 16.04. Instructions for: * rbenv * PostgreSQL * git * figaro * Update manual installation doc with feedback from @mrcasals and @deivid-rodriguez * Change typo on guy/guide * PostgreSQL installation before installing Decidim * Removing bundle install on Decidim installation * Adds sekrets/encrypted secrets mention on secrets handling * Change postgreSQL database/user creation * Removing trailing white space * Adding servers/technologies on manual installation * Markdown format: Adds language to fenced code block * Adds mention to rvm * Remove white trailing space :/ * Changes details with feedback from @deivid-rodriguez

Digharatta · 2018-06-11T07:39:33Z

Thank you very much for the guide. With the help of it, plus GoRails guide and ImageMagick guide I finally managed to launch a first shaky Ukrainian deployment.

On one hand, GoRails guide is indispensable, since it gives precise, updated, and version-sensitive instructions. On the other hand, I needed PostgreSQL instructions from your guide, since they are app-specific. GoRails PostgreSQL instructions weren't suitable.

IMHO some parts of the guide can be outsourced, with links to appropriate resources, e.g.:

Install Ruby, NodeJS and Nginx

As described at (URLs)

Install PostgreSQL

sudo apt-get install -y postgresql libpq-dev
sudo -u postgres psql -c "CREATE USER decidim_app WITH SUPERUSER CREATEDB NOCREATEROLE PASSWORD 'thepassword'"

etc.

Install ImageMagick

As described at (URLs)

Install Decidim
gem install decidim etc.

Configure Nginx and hide the secrets

As described at (URLs).

IMHO, local setup guide and deployment guide should be separate.

Adds documentation for manual installation on Ubuntu LTS 16.04.

64b44bd

Instructions for: * rbenv * PostgreSQL * git * figaro

ghost assigned andreslucena Mar 2, 2018

ghost added the in-progress label Mar 2, 2018

andreslucena commented Mar 2, 2018

View reviewed changes

mrcasals reviewed Mar 2, 2018

View reviewed changes

andreslucena commented Mar 2, 2018

View reviewed changes

deivid-rodriguez reviewed Mar 2, 2018

View reviewed changes

oriolgual added status: WIP and removed status: WIP in-progress labels Mar 16, 2018

andreslucena added 4 commits April 17, 2018 12:05

Removing trailing white space

bf933e8

Adding servers/technologies on manual installation

e206618

Merge branch 'master' into docs/manual-installation

8150cfb

Markdown format: Adds language to fenced code block

303f7df

andreslucena mentioned this pull request Apr 20, 2018

Master is too unstable #3218

Closed

Adds mention to rvm

2f329b0

Remove white trailing space :/

7025345

andreslucena mentioned this pull request Apr 20, 2018

Code Climate configuration: removes execution for documentation files #3263

Closed

deivid-rodriguez reviewed Apr 24, 2018

View reviewed changes

Merge branch 'master' into docs/manual-installation

478fb34

ghost assigned tramuntanal May 2, 2018

tramuntanal removed their assignment May 3, 2018

Changes details with feedback from @deivid-rodriguez

a2aac9f

deivid-rodriguez approved these changes May 7, 2018

View reviewed changes

mrcasals merged commit f8c7302 into master May 8, 2018

ghost removed the status: WIP label May 8, 2018

mrcasals deleted the docs/manual-installation branch May 8, 2018 07:12

andreslucena mentioned this pull request Jul 20, 2021

Update manual installation guide in documentation #8217

Merged

snyk-bot mentioned this pull request Jan 12, 2022

[Snyk] Security upgrade axios from 0.18.1 to 0.20.0 OpenSourcePolitics/decidim#1169

Closed

snyk-bot mentioned this pull request Feb 10, 2022

[Snyk] Security upgrade axios from 0.18.1 to 0.20.0 OpenSourcePolitics/decidim#1174

Closed


		## Step by step

		We're starting with an Ubuntu 16.04 LTS. This is an opinionated guy and YMMV, so if you're free to use the technology that you fell most comfortable on. If you have any doubts and you're blocked you can go and ask on [our Gitter](https://gitter.im/decidim/decidim). We recommend that you follow some Ruby on Rails tutorials (like [Getting Started with Ruby on Rails](http://guides.rubyonrails.org/getting_started.html)) and have some knowledge on how gems and engines work.

Uh oh!

Conversation

andreslucena commented Mar 2, 2018

🎩 What? Why?

📌 Related Issues

📋 Subtasks

📷 Screenshots (optional)

Uh oh!

andreslucena Mar 2, 2018 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mrcasals commented Mar 2, 2018

Uh oh!

deivid-rodriguez Mar 2, 2018 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

deivid-rodriguez Mar 2, 2018 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

deivid-rodriguez commented Mar 2, 2018

Uh oh!

andreslucena commented Mar 9, 2018

Uh oh!

xabier commented Mar 20, 2018

Uh oh!

deivid-rodriguez commented Apr 9, 2018

Uh oh!

andreslucena commented Apr 10, 2018

Uh oh!

mrcasals commented Apr 11, 2018

Uh oh!

codecov bot commented Apr 12, 2018 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

andreslucena commented Apr 20, 2018

Uh oh!

andreslucena commented Apr 20, 2018

Uh oh!

andreslucena commented Apr 24, 2018

Uh oh!

deivid-rodriguez left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

andreslucena commented May 7, 2018

Uh oh!

deivid-rodriguez left a comment

Choose a reason for hiding this comment

Uh oh!

andreslucena Mar 2, 2018 •

edited

Loading

deivid-rodriguez Mar 2, 2018 •

edited

Loading

deivid-rodriguez Mar 2, 2018 •

edited

Loading

codecov bot commented Apr 12, 2018 •

edited

Loading