Public | Automated Build

Last pushed: 2 months ago
Short Description
Fab manager provides an open source platform and custom made support services for fab labs
Full Description


FabManager is the FabLab management solution. It is web-based, open-source and totally free.

Table of Contents
  1. Software stack
  2. Contributing
  3. Setup a production environment
  4. Setup a development environment<br/>
    4.1. General Guidelines<br/>
    4.2. Environment Configuration
    4.3. Virtual Machine Instructions<br/>
  5. PostgreSQL<br/>
    5.1. Install PostgreSQL 9.4 on Ubuntu/Debian<br/>
    5.2. Install and launch PostgreSQL on MacOS X<br/>
    5.3. Setup the FabManager database in PostgreSQL<br/>
    5.4. PostgreSQL Limitations
  6. ElasticSearch<br/>
    6.1. Install ElasticSearch on Ubuntu/Debian<br/>
    6.2. Install ElasticSearch on MacOS X<br/>
    6.3. Setup ElasticSearch for the FabManager<br/>
    6.4. Backup and Restore
  7. Internationalization (i18n)<br/>
    7.1. Translation<br/>
    7.1.1. Front-end translations<br/>
    7.1.2. Back-end translations<br/>
    7.2. Configuration<br/>
    7.2.1. Settings<br/>
    7.2.2. Applying changes
  8. Open Projects
  9. Plugins
  10. Single Sign-On
  11. Known issues
  12. Related Documentation

<a name="software-stack"></a>

Software stack

FabManager is a Ruby on Rails / AngularJS web application that runs on the following software:

  • Ubuntu LTS 14.04+ / Debian 8+
  • Ruby 2.3
  • Git 1.9.1+
  • Redis 2.8.4+
  • Sidekiq 3.3.4+
  • Elasticsearch 1.7
  • PostgreSQL 9.4

<a name="contributing"></a>


Contributions are welcome. Please read the contribution guidelines for more information about the contribution process.

<a name="setup-a-production-environment"></a>

Setup a production environment

To run fab-manager as a production application, this is highly recommended to use Docker.
The procedure to follow is described in the docker readme.

<a name="setup-a-development-environment"></a>

Setup a development environment

In you intend to run fab-manager on your local machine to contribute to the project development, you can set it up with the following procedure.
This procedure is not easy to follow so if you don't need to write some code for Fab-manager, please prefer the docker installation method.

<a name="general-guidelines"></a>

General Guidelines

  1. Install RVM with the ruby version specified in the .ruby-version file.
    For more details about the process, Please read the official RVM documentation.
    If you're using ArchLinux, you may have to read this before.

  2. Retrieve the project from Git

    git clone
  3. Install the software dependencies.
    First install PostgreSQL and ElasticSearch as specified in their respective documentations.
    Then install the other dependencies:

    • For Ubuntu/Debian:
    sudo apt-get install libpq-dev redis-server imagemagick
    • For MacOS X:
    brew install redis imagemagick
  4. Init the RVM instance and check it was correctly configured

    cd fab-manager
    rvm current
    # Must print ruby-X.Y.Z@fab-manager (where X.Y.Z match the version in .ruby-version)
  5. Install bundler in the current RVM gemset

    gem install bundler
  6. Install the required ruby gems

    bundle install
  7. Create the default configuration files and configure them! (see the Environment Configuration section)

    cp config/database.yml.default config/database.yml
    cp config/application.yml.default config/application.yml
    vi config/application.yml
    # or use your favorite text editor instead of vi (nano, ne...)
  8. Build the database. You may have to follow the steps described in the PostgreSQL configuration chapter before, if you don't already had done it.
    Warning: NO NOT run rake db:setup instead of these commands, as this will not run some required raw SQL instructions.

    rake db:create
    rake db:migrate
    ADMIN_EMAIL='youradminemail' ADMIN_PASSWORD='youradminpassword' rake db:seed
  9. Create the pids folder used by Sidekiq. If you want to use a different location, you can configure it in config/sidekiq.yml

    mkdir -p tmp/pids
  10. Start the development web server

    foreman s -p 3000
  11. You should now be able to access your local development FabManager instance by accessing http://localhost:3000 in your web browser.

  12. You can login as the default administrator using the following credentials:

  13. Email notifications will be caught by MailCatcher.
    To see the emails sent by the platform, open your web browser at http://localhost:1080 to access the MailCatcher interface.

<a name="environment-configuration"></a>

Environment Configuration

The settings in config/application.yml configure the environment variables of the application.
If you are in a development environment, your can keep the default values, otherwise, in production, values must be configured carefully.


DNS name or IP address of the server hosting the PostgreSQL database of the application (see PostgreSQL).
This value is only used when deploying with Docker, otherwise this is configured in config/database.yml.


Password for the PostgreSQL user, as specified in database.yml.
Please see Setup the FabManager database in PostgreSQL for information on how to create a user and set his password.
This value is only used when deploying with Docker, otherwise this is configured in config/database.yml.


DNS name or IP address of the server hosting the redis database.


DNS name or IP address of the server hosting the elasticSearch database.


Used by the authentication system to generate random tokens, eg. for resetting passwords.
Used by Rails to verify the integrity of signed cookies.
You can generate such a random key by running rake secret.


Key and secret used to identify you Stripe account through the API.
Retrieve them from


Currency used by stripe to charge the final customer.
See for a list of available 3-letters ISO code.

BEWARE: stripe currency cannot be changed during the application life.
Changing the currency after the application has already run, may result in several bugs and prevent the users to pay through stripe.
So set this setting carefully before starting the application for the first time.


When payments are done on the platform, an invoice will be generated as a PDF file.
The PDF file name will be of the form "(INVOICE_PREFIX) - (invoice ID) _ (invoice date) .pdf"


If set to 'true', the subscription plans will be fully disabled and invisible in the application.
It is not recommended to disable plans if at least one subscription was took on the platform.


If set to 'false', enable the spaces management and reservation in the application.
It is not recommended to disable spaces if at least one space reservation was made on the system.


When sending notification mails, the platform will use this address to identify the sender.


Configure the Rails' Action Mailer delivery method.
See for more details.


When DELIVERY_METHOD is set to smtp, configure the SMTP server parameters.
See for more details.
DEFAULT_HOST is also used to configure Google Analytics.


Identifier of your Google Analytics account.


Unique identifier of your Disqus forum.
Disqus forums are used to allow visitors to comment on projects.
See for more information.


Identifier of the Twitter account, from witch the last tweet will be fetched and displayed on the home page.
This value can be graphically overridden during the application's lifecycle in Admin/Customization/Home page/Twitter Feed.
It will also be used for Twitter Card analytics.


Keys and secrets to access the twitter API.
Retrieve them from


This is optional. You can follow this guide to get your personal App ID.
If you do so, you'll be able to customize and get statistics about project shares on Facebook.


This parameter configures the logs verbosity.
Available log levels can be found here.


Exhaustive list of file's extensions available for public upload as project's CAO attachements.
Each item in the list must be separated from the others by a space char.
You will probably want to check that this list match the ALLOWED_MIME_TYPES values below.
Please consider that allowing file archives (eg. ZIP) or binary executable (eg. EXE) may result in a dangerous security issue and must be avoided in any cases.


Exhaustive list of file's mime-types available for public upload as project's CAO attachements.
Each item in the list must be separated from the others by a space char.
You will probably want to check that this list match the ALLOWED_EXTENSIONS values above.
Please consider that allowing file archives (eg. application/zip) or binary executable (eg. application/exe) may result in a dangerous security issue and must be avoided in any cases.


Maximum size (in bytes) allowed for image uploaded on the platform.
This parameter concerns events, plans, user's avatars, projects and steps of projects.
If this parameter is not specified the maximum size allowed will be 2MB.


Credentials for the first admin user created when seeding the project. (not present in application.yml because they are only used once when running the database seed with the command rake db:seed)

Settings related to Open Projects

See the Open Projects section for a detailed description of these parameters.

Settings related to i18n

See the Settings section of the Internationalization (i18n) paragraph for a detailed description of these parameters.

<a name="virtual-machine-instructions"></a>

Virtual Machine Instructtions

These instructions allow to deploy a testing or development instance of Fab Manager inside a virtual
machine, with most of the software dependencies installed automatically and avoiding to install a lot
of software and services directly on the host computer.

Note: The provision scripts configure the sofware dependencies to play nice with each other while
they are inside the same virtual environment but said configuration is not optimized for a production

  1. Install Vagrant and Virtual Box (with the extension package).

  2. Retrieve the project from Git

    git clone
  3. From the project directory, run:

    vagrant up
  4. Once the virtual machine finished building, reload it with:

    vagrant reload
  5. Log into the virtual machine with:

    vagrant ssh
  6. While logged in, navigate to the project folder and install the Gemfile

    cd /vagrant
    bundle install
  7. Set a directory for Sidekick pids:

    mkdir -p tmp/pids
  8. Copy the default configuration files:

    cp config/database.yml.virtual config/database.yml
    cp config/application.yml.default config/application.yml
  9. Set up the databases. (Note that you should provide the desired admin credentials and that these
    specific set of commands must be used to set up the database as some raw SQL instructions are
    included in the migrations):

    rake db:create
    rake db:migrate
    ADMIN_EMAIL='youradminemail' ADMIN_PASSWORD='youradminpassword' rake db:seed
    rake fablab:es_build_stats
  10. Start the application and visit localhost:3000 on your browser to check that it works:

    foreman s -p 3000

<a name="postgresql"></a>


<a name="postgresql-on-debian"></a>

Install PostgreSQL 9.4 on Ubuntu/Debian

  1. Create the file /etc/apt/sources.list.d/pgdg.list, and append it one your distribution source:
    sudo sh -c 'echo "deb $(lsb_release -cs)-pgdg main" > /etc/apt/sources.list.d/pgdg.list'
  1. Import the repository signing key, and update the package lists

    wget --quiet -O - | sudo apt-key add -
    sudo apt-get update
  2. Install PostgreSQL 9.4

    sudo apt-get install postgresql-9.4

<a name="postgresql-on-macosx"></a>

Install and launch PostgreSQL on MacOS X

This assumes you have Homebrew installed on your system.
Otherwise, please follow the official instructions on the project's website.

  1. Update brew and install PostgreSQL

    brew update
    brew install homebrew/versions/postgresql94
  2. Launch PostgreSQL

    # Start postgresql at login with launchd
    ln -sfv /usr/local/opt/postgresql/*.plist ~/Library/LaunchAgents
    # Load PostgreSQL now
    launchctl load ~/Library/LaunchAgents/homebrew.mxcl.postgresql.plist

<a name="setup-fabmanager-in-postgresql"></a>

Setup the FabManager database in PostgreSQL

Before running rake db:create, you have to make sure that the user configured in config/database.yml for the development environment exists.
To create it, please follow these instructions:

  1. Run the PostgreSQL administration command line interface, logged as the postgres user

    • For Ubuntu/Debian:
    sudo -i -u postgres
    • For MacOS X:
    sudo psql -U $(whoami) postgres

    If you get an error running this command, please check your pg_hba.conf file.

  2. Create a new user in PostgreSQL (in this example, the user will be named sleede)

    CREATE USER sleede;
  3. Grant him the right to create databases

  4. Then, attribute a password to this user

  5. Finally, have a look at the PostgreSQL Limitations section or some errors will occurs preventing you from finishing the installation procedure.

<a name="postgresql-limitations"></a>

PostgreSQL Limitations

  • While setting up the database, we'll need to activate two PostgreSQL extensions: unaccent and trigram.
    This can only be achieved if the user, configured in config/database.yml, was granted the SUPERUSER role OR if these extensions were white-listed.
    So here's your choices, mainly depending on your security requirements:

    • Use the default PostgreSQL super-user (postgres) as the database user of fab-manager.
    • Set your user as SUPERUSER; run the following command in psql (after replacing sleede with you user name):

    • Install and configure the PostgreSQL extension pgextwlist.
      Please follow the instructions detailed on the extension website to whitelist unaccent and trigram for the user configured in config/database.yml.

  • Some users may want to use another DBMS than PostgreSQL.
    This is currently not supported, because of some PostgreSQL specific instructions that cannot be efficiently handled with the ActiveRecord ORM:
    • app/controllers/api/members_controllers.rb@list is using ILIKE
    • app/controllers/api/invoices_controllers.rb@list is using ILIKE and date_trunc()
    • db/migrate/20160613093842_create_unaccent_function.rb is using unaccent and trigram modules and defines a PL/pgSQL function (f_unaccent())
    • app/controllers/api/members_controllers.rb@search is using f_unaccent() (see above) and regexp_replace()
    • db/migrate/20150604131525_add_meta_data_to_notifications.rb is using jsonb, a PostgreSQL 9.4+ datatype.
    • db/migrate/20160915105234_add_transformation_to_o_auth2_mapping.rb is using jsonb, a PostgreSQL 9.4+ datatype.
  • If you intend to contribute to the project code, you will need to run the test suite with rake test.
    This also requires your user to have the SUPERUSER role.
    Please see the known issues section for more information about this.

<a name="elasticsearch"></a>


ElasticSearch is a powerful search engine based on Apache Lucene combined with a NoSQL database used as a cache to index data and quickly process complex requests on it.

In FabManager, it is used for the admin's statistics module and to perform searches in projects.

<a name="elasticsearch-on-debian"></a>

Install ElasticSearch on Ubuntu/Debian

For a more detailed guide concerning the ElasticSearch installation, please check the official documentation

  1. Install the OpenJDK's Java Runtime Environment (JRE). ElasticSearch recommends that you install Java 8 update 20 or later.
    Please check that your distribution's version meet this requirement.

    sudo apt-get install openjdk-8-jre
  2. Create the file /etc/apt/sources.list.d/elasticsearch-1.x.list, and append it the following line:
    deb stable main

  3. Import the repository signing key, and update the package lists

    wget -qO - | sudo apt-key add -
    sudo apt-get update
  4. Install ElasticSearch 1.7

    sudo apt-get install elasticsearch
  5. To automatically start ElasticSearch during bootup, then, depending if your system is compatible with SysV (eg. Ubuntu 14.04) or uses systemd (eg. Debian 8+/Ubuntu 16.04+), you will need to run:

    # System V
    sudo update-rc.d elasticsearch defaults 95 10
    # *** OR *** (systemd)
    sudo /bin/systemctl daemon-reload
    sudo /bin/systemctl enable elasticsearch.service
  6. Restart the host operating system to complete the installation

    sudo reboot

<a name="elasticsearch-on-macosx"></a>

Install ElasticSearch on MacOS X

This assumes you have Homebrew installed on your system.
Otherwise, please follow the official instructions on the project's website.

brew update
brew install homebrew/versions/elasticsearch17

<a name="setup-fabmanager-in-elasticsearch"></a>

Setup ElasticSearch for the FabManager

  1. Launch the associated rake tasks in the project folder.
    This will create the fields mappings in ElasticSearch DB

    rake fablab:es_build_stats
  2. Every nights, the statistics for the day that just ended are built automatically at 01:00 (AM).
    See schedule.yml to modify this behavior.
    If the scheduled task wasn't executed for any reason (eg. you are in a dev environment and your computer was turned off at 1 AM), you can force the statistics data generation in ElasticSearch, running the following command.

    # Here for the 50 last days
    rake fablab:generate_stats[50]

<a name="backup-and-restore-elasticsearch"></a>

Backup and Restore

To backup and restore the ElasticSearch database, use the elasticsearch-dump tool.

Dump the database with: elasticdump --input=http://localhost:9200/stats --output=fablab_stats.json.
Restore it with: elasticdump --input=fablab_stats.json --output=http://localhost:9200/stats.

<a name="i18n"></a>

Internationalization (i18n)

The FabManager application can only run in a single language but this language can easily be changed.

<a name="i18n-translation"></a>


Check the files located in config/locales:

  • Front app translations (angular.js) are located in config/locales/app.scope.XX.yml.
    Where scope has one the following meaning :
    • admin: translations of the administrator views (manage and configure the FabLab).
    • logged: translations of the end-user's views accessible only to connected users.
    • public: translation of end-user's views publicly accessible to anyone.
    • shared: translations shared by many views (like forms or buttons).
  • Back app translations (Ruby on Rails) are located in config/locales/XX.yml.
  • Emails translations are located in config/locales/mails.XX.yml.
  • Messages related to the authentication system are located in config/locales/devise.XX.yml.

If you plan to translate the application to a new locale, please consider that the reference translation is French.
Indeed, in some cases, the English texts/sentences can seems confuse or lack of context as they were originally translated from French.

To prevent syntax mistakes while translating locale files, we STRONGLY advise you to use a text editor witch support syntax coloration for YML and Ruby.

<a name="i18n-translation-front"></a>

Front-end translations

Front-end translations uses angular-translate with some interpolations interpreted by angular.js and other interpreted by MessageFormat.
These two kinds of interpolation use a near but different syntax witch SHOULD NOT be confused.
Please refer to the official angular-translate documentation before translating.

<a name="i18n-translation-back"></a>

Back-end translations

Back-end translations uses the Ruby on Rails syntax but some complex interpolations are interpreted by MessageFormat and are marked as it in comments.
DO NOT confuse the syntaxes.

In each cases, some inline comments are included in the localisation files.
They can be recognized as they start with the sharp character (#).
These comments are not required to be translated, they are intended to help the translator to have some context information about the sentence to translate.

<a name="i18n-configuration"></a>


Locales configurations are made in config/application.yml.
If you are in a development environment, your can keep the default values, otherwise, in production, values must be configured carefully.

<a name="i18n-settings"></a>



Configure application's main localization and translation settings.

See config/locales/app.*.yml for a list of available locales. Default is en.


Configure Ruby on Rails localization settings (currency, dates, number formats ...).

Please, be aware that the configured locale will imply the CURRENCY symbol used to generate invoices.

_Eg.: configuring es-ES will set the currency symbol to but es-MX will set $ as currency symbol, so setting the RAILS_LOCALE to simple es (without country indication) will probably not do what you expect._

See config/locales/rails.*.yml for a list of available locales. Default is en.

If your locale is not present in that list or any locale doesn't have your exact expectations, please open a pull request to share your modifications with the community and obtain a rebuilt docker image.
You can find templates of these files at


Configure the moment.js library for l10n.

See vendor/assets/components/moment/locale/*.js for a list of available locales.
Default is en (even if it's not listed).


Configure the javascript summernote editor for l10n.

See vendor/assets/components/summernote/lang/summernote-*.js for a list of available locales.
Default is en-US (even if it's not listed).


Configure the locale for angular-i18n.

Please, be aware that the configured locale will imply the CURRENCY displayed to front-end users.

_Eg.: configuring fr-fr will set the currency symbol to but fr-ca will set $ as currency symbol, so setting the ANGULAR_LOCALE to simple fr (without country indication) will probably not do what you expect._

See vendor/assets/components/angular-i18n/angular-locale_*.js for a list of available locales. Default is en.


Configure the messageformat.js library, used by angular-translate.

See vendor/assets/components/messageformat/locale/*.js for a list of available locales.


Configure the fullCalendar JS agenda library.

See vendor/assets/components/fullcalendar/dist/lang/*.js for a list of available locales. Default is en (even if it's not listed).


This configure the language analyzer for indexing and searching in projects with ElasticSearch.
See for a list of available analyzers (check that the doc version match your installed elasticSearch version).


In Rails: set default to the specified zone and make Active Record auto-convert to this zone. Run rake time:zones:all for a list of available time zone names.
Default is UTC.


Configure the first day of the week in your locale zone (generally monday or sunday).


Date format for dates displayed in statistics charts.
See for available formats.


Date format for dates displayed and parsed in date pickers.
See for a list available formats.

BEWARE: years format with less than 4 digits will result in problems because the system won't be able to distinct dates with the same less significant digits, eg. 50 could mean 1950 or 2050.


Date format for dates shown in exported Excel files (eg. statistics)
See for a list a available formats.

<a name="i18n-apply"></a>

Applying changes

After modifying any values concerning the localisation, restart the application (ie. web server) to apply these changes in the i18n configuration.

<a name="open-projects"></a>

Open Projects

This configuration is optional.

You can configure your fab-manager to synchronize every project with the Open Projects platform. It's very simple and straightforward and in return, your users will be able to search over projects from all fab-manager instances from within your platform. The deal is fair, you share your projects and as reward you benefits from projects of the whole community.

If you want to try it, you can visit this fab-manager and see projects from different fab-managers.

To start using this awesome feature, there are a few steps:

  • send a mail to **** asking for your Open Projects client's credentials and giving them the name of your fab-manager, they will give you an OPENLAB_APP_ID and an OPENLAB_APP_SECRET
  • fill in the value of the keys in your application.yml
  • start your fab-manager app
  • export your projects to open-projects (if you already have projects created on your fab-manager, unless you can skip that part) executing this command: bundle exec rake fablab:openlab:bulk_export

IMPORTANT: please run your server in production mode.

Go to your projects gallery and enjoy seeing your projects available from everywhere ! That's all.

<a name="plugins"></a>


Fab-manager has a system of plugins mainly inspired by Discourse architecture.

It enables you to write plugins which can:

  • have its proper models and database tables
  • have its proper assets (js & css)
  • override existing behaviours of Fab-manager
  • add features by adding views, controllers, ect...

To install a plugin, you just have to copy the plugin folder which contains its code into the folder plugins of Fab-manager.

You can see an example on the repo of navinum gamification plugin

<a name="sso"></a>

Single Sign-On

Fab-manager can be connected to a Single Sign-On server which will provide its own authentication for the platform's users.
Currently OAuth 2 is the only supported protocol for SSO authentication.

For an example of how to use configure a SSO in Fab-manager, please read
Developers may find information on how to implement their own authentication protocol in

<a name="known-issues"></a>

Known issues

  • When browsing a machine page, you may encounter an "InterceptError" in the console and the loading bar will stop loading before reaching its ending.
    This may happen if the machine was created through a seed file without any image.
    To solve this, simply add an image to the machine's profile and refresh the web page.

  • When starting the Ruby on Rails server (eg. foreman s) you may receive the following error:

      worker.1 | invalid url: redis::6379
      web.1    | Exiting
      worker.1 | ...lib/redis/client.rb...:in `_parse_options'

    This may happen when the application.yml file is missing.
    To solve this issue copy config/application.yml.default to config/application.yml.
    This is required before the first start.

  • Due to a stripe limitation, you won't be able to create plans longer than one year.

  • When running the tests suite with rake test, all tests may fail with errors similar to the following:

      ActiveRecord::InvalidForeignKey: PG::ForeignKeyViolation: ERROR:  insert or update on table "..." violates foreign key constraint "fk_rails_..."
      DETAIL:  Key (group_id)=(1) is not present in table "groups".
      : ...
          test_after_commit (1.0.0) lib/test_after_commit/database_statements.rb:11:in `block in transaction'
          test_after_commit (1.0.0) lib/test_after_commit/database_statements.rb:5:in `transaction'

    This is due to an ActiveRecord behavior witch disable referential integrity in PostgreSQL to load the fixtures.
    PostgreSQL will prevent any users to disable referential integrity on the fly if they doesn't have the SUPERUSER role.
    To fix that, logon as the postgres user and run the PostgreSQL shell (see Setup the FabManager database in PostgreSQL for an example).
    Then, run the following command (replace sleede with your test database user, as specified in your database.yml):


    DO NOT do this in a production environment, unless you know what you're doing: this could lead to a serious security issue.

  • With Ubuntu 16.04, ElasticSearch may refuse to start even after having configured the service with systemd.
    To solve this issue, you may have to set START_DAEMON to true in /etc/default/elasticsearch.
    Then reload ElasticSearch with:

    sudo systemctl restart elasticsearch.service

<a name="related-documentation"></a>

Related Documentation

Docker Pull Command
Source Repository