Skip to content

Deployment v0.8

Jump to bottom
daronco edited this page Sep 26, 2014 · 11 revisions

→ For Mconf-Web version 0.8.

Overview

This is a step-by-step guide showing every detail needed to install Mconf-Web. If you have experience deploying a Rails application this guide should look very familiar to you.

Mconf-Web is developed in and targeted to Ubuntu systems. We recommend the use of an specific version of Ubuntu (see below), but it has been tested in newer versions and should work as well (however some instructions might have to be adapted).

The recommended setup for this version of Mconf-Web is:

  1. Ubuntu 12.04 operating system with a user named mconf.
  2. Ruby is installed with RVM.
  3. Phusion Passenger (ruby app server).
  4. Apache (but you can also use Nginx).
  5. MySQL database.

This guide will instruct you on how to setup this environment.

Mconf-Web can also be adapted to your needs. It is a Ruby on Rails application, so the deployment process is very similar to the deployment of any other Rails application. It should work on any operating system that has Ruby available (and most of them do). But be aware that changing any of these components will probably require modifications in the configuration files and scripts (and maybe even some code changes).

Installing Mconf-Web

System Packages

You need to install some system packages before you can run Mconf-web in production:

$ sudo apt-get update
$ sudo apt-get install curl make git-core libruby aspell-es aspell-en \
                       libxml2-dev libxslt1-dev libmagickcore-dev \
                       libmagickwand-dev imagemagick libmysqlclient-dev \
                       mysql-server zlib1g-dev build-essential \
                       libreadline-dev nfs-common libcurl4-openssl-dev

You will be prompted to type a password for MySQL's root user in case you don't MySQL installed yet.

Ruby

Mconf-web uses Ruby 1.9.2 (p290). To install Ruby, we suggest the use of RVM (that's how we install ruby in development and production). But you have other options:

  • Using RVM (recommended): See this page. RVM can be installed as single-user or multi-user. For a production environment it is recommended to use the multi-user installation.
  • Using apt packages: Ruby can also be installed using apt packages in Ubuntu, but unfortunately they are out of date. Installing ruby 1.9.2 would actually install version 1.9.2-p0 instead of 1.9.2-p290. BigBlueButton 0.8 uses a nice script to compile ruby from source and install it as a package that you can see here.
  • From source: You can also download and install ruby manually, similarly to what's done in the script used by BigBlueButton but skipping the packaging. Make sure you use version 1.9.2-p290.

From now on, we will assume you will install ruby with RVM, so if you decide for another method you might have to adapt some commands.

To install RVM run:

$ curl -L https://get.rvm.io | sudo bash -s stable --without-gems="bundler"

This will install the latest version of RVM skipping the gem bundler. We skip it because we need to install an specific version later on. In case you have any problems refer to RVM's documentation at https://rvm.io/rvm/install/.

The first thing after the installation is to add your user to the rvm group:

$ sudo adduser mconf rvm # change "mconf" to your username

After that, restart your terminal! If you don't do that, RVM won't be found and your user's permissions won't be updated.

Before installing ruby, run the command below to see the dependencies RVM requires you to install before ruby. It will show you a apt-get command right below the header "For Ruby / Ruby HEAD (MRI, Rubinius, & REE)". Install the packages listed there before proceeding.

$ rvm requirements

Install ruby and create a gemset for Mconf-web:

$ rvm install 1.9.2-p290
# if you get a "checksum error", run this command again with:
#   rvm reinstall 1.9.2-p290 --verify-downloads 1

$ rvm gemset create mconf
$ rvm use --default 1.9.2-p290@mconf

Then install bundler in the gemset global to be available to all other gemsets:

$ rvm use 1.9.2-p290@global
$ gem install bundler -v 1.3.4
$ rvm use 1.9.2-p290@mconf

Download the application

Install git if you don't have it and clone Mconf-Web:

$ mkdir -p ~/mconf-web/current/
$ git clone git://github.com/mconf/mconf-web.git ~/mconf-web/current/

Your application will be deployed at ~/mconf-web/current/, but you can change it if you need to. It is the default path, so it should require less configurations if you don't change it.

The first thing is to mark the .rvmrc as trusted (you can read more about here). This is specially useful later on when other processes are executed (god and delayed_job) and needs this to be done:

$ rvm rvmrc trust ~/mconf-web/current/.rvmrc

Next, change your repository to the version you will be deploying:

$ cd ~/mconf-web/current
$ git checkout v0.8.1

With the repository you can now install the dependencies. All dependencies are either gems (and are listed in the Gemfile) or submodules. Run the commands below:

$ git submodule init
$ git submodule update
$ bundle install --without=development test

Edit the configuration files

There are two files that need to be configured. At first, copy the example files:

$ cp ~/mconf-web/current/config/setup_conf.yml.example ~/mconf-web/current/config/setup_conf.yml
$ cp ~/mconf-web/current/config/database.yml.example ~/mconf-web/current/config/database.yml

See below what you have to edit in setup_conf.yml and database.yml:

  • database.yml configures the database and it must be configured now. By default, MySQL will be used. You only need to set the variables username and password (for all environments) with the user that will be used to access MySQL and his password. We recommend a user other than root (usually mconf). See the section 4.1. below how to create this user.

  • setup_conf.yml has general configurations for the web application and it's optional right now: if you don't edit it now you can edit its properties from Mconf-Web's interface (see this page). Note: if you don't edit this file, by default the administrator account will use the email admin@default.com, login admin and password admin.

To learn more about the other options in these files, see this page.

Database user

This section explains how to create a database user named mconf and give him access to the databases used by Mconf-Web.

First open MySQL's console (you will have to enter the password for the root user):

$ mysql -u root -p

(If you're having trouble with the root password in MySQL, see this FAQ entry.)

Then create the user (change all occurrences of password by the actual password that should be used):

CREATE USER "mconf"@"localhost" IDENTIFIED BY "password";
GRANT ALL PRIVILEGES ON mconf_production.* TO "mconf"@"localhost" IDENTIFIED BY "password";
FLUSH PRIVILEGES;

Application configurations

This step consists of everything that was not possible to be done before because we needed the configuration files properly edited.

We'll setup the database and generate a new secret key for rails.

(These commands will drop your old database (if any) and create a new one, empty. Be careful if you're running it again after using the application.)

$ cd ~/mconf-web/current
$ RAILS_ENV=production bundle exec rake db:drop db:create db:reset
$ RAILS_ENV=production bundle exec rake secret

Web server

Mconf-Web uses Apache and Passenger to serve the application. See the guide below to learn how to install both of them:

After installing and configuring Apache and Passenger, you should already be able to access your application in your browser!

System-wide configurations

This contains the extra configurations you need to do on your server to run Mconf-Web.

At this point you finished installing Mconf-Web. The first thing you might want to do is configure the application.

Maintenance tasks

Restart

To restart the application you need to restart the web server and god:

$ sudo service apache2 restart
$ sudo /etc/init.d/god terminate
$ sudo /etc/init.d/god start

The web server you'll need to restart every time you change anything in the application (source code) or configuration files.

You don't always need to restart god, only if you changed anything in its configuration files or in files that the monitored processes use (for example, if you change the Gmail account settings used to send emails). If you're not sure, restart it. Also, we use the action "terminate" so that god will also stop all monitored processes before stopping itself. It will, for instance, stop delayed_job (a gem used to send emails) and then, when god is restarted, delayed_job will also be restarted (and so your new configurations will be applied).

Backup

The most important backup you need is your database. If you're using MySQL, you can use the following commands to backup (and restore) the database used by Mconf-Web:

# backup
$ mysqldump -u root -p mconf_production > mconf_production-`date +%F`.sql

# restore
$ mysql -u root -p mconf_production < mconf_production-2011-06-21.sql

There are also files that are not stored in the database, such as user images and attachments. And you also might want to backup your log files.

So make sure you backup the files in the following folders:

(...)/mconf-web/attachments/
(...)/mconf-web/public/logos/
(...)/mconf-web/log/

Update

Follow the steps below to update from minor versions of 0.8 (e.g. from 0.8 to 0.8.1). Do not use it for versions other than 0.8.

At first, update your repository and checkout the version you want:

$ cd ~/mconf-web/current
$ git pull
$ git checkout v0.8.1

Update the dependencies:

$ git submodule update
$ bundle install --without=development test

Migrate the database:

$ RAILS_ENV=production bundle exec rake db:migrate

Update the crontab:

$ RAILS_ENV=production bundle exec whenever --update-crontab

There are also other files that might need to be updated, such as the configuration files for god, that will not be configured with the commands above. To check if you need to do any extra work, check the update notes in the changelog page.

Restart the web server as described previously.

This is the technical documentation for Mconf-Web, a component of Mconf. Read more about the project and try it out at mconf.org.

Clone this wiki locally