rooty/fab-manager
1
0
Fork 0
mirror of https://github.com/LaCasemate/fab-manager.git synced 2024-12-01 12:24:28 +01:00
Code Issues Releases Activity
d1450f65f6
fab-manager/README.md
cyril d1450f65f6 release 2.0 rc
2016-03-23 18:39:41 +01:00

534 lines
19 KiB
Markdown
Raw Blame History

# FabManager
FabManager is the FabLab management solution. It is web-based, open-source and totally free.
##### Table of Contents
1. [Software stack](#software-stack)
2. [Contributing](#contributing)
3. [Setup a development environment](#setup-a-development-environment)
3.1 [General Guidelines](#general-guidelines)
3.2 [Environment Configuration](#environment-configuration)
4. [PostgreSQL](#postgresql)
4.1 [Install PostgreSQL 9.4 on Ubuntu/Debian](#postgresql-on-debian)
4.2 [Install and launch PostgreSQL on MacOS X](#postgresql-on-macosx)
4.3 [Setup the FabManager database in PostgreSQL](#setup-fabmanager-in-postgresql)
5. [ElasticSearch](#elasticsearch)
5.1 [Install ElasticSearch on Ubuntu/Debian](#elasticsearch-on-debian)
5.2 [Install ElasticSearch on MacOS X](#elasticsearch-on-macosx)
5.3 [Setup ElasticSearch for the FabManager](#setup-fabmanager-in-elasticsearch)
6. [Internationalization (i18n)](#i18n)
6.1 [Translation](#i18n-translation)
6.1.1 [Front-end translations](#i18n-translation-front)
6.1.2 [Back-end translations](#i18n-translation-back)
6.2 [Configuration](#i18n-configuration)
6.2.1 [Settings](#i18n-settings)
6.2.2 [Applying changes](#i18n-apply)
7. [Known issues](#known-issues)
8. [Related Documentation](#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/Debian
- Ruby 2.2.3
- Git 1.9.1+
- Redis 2.8.4+
- Sidekiq 3.3.4+
- Elasticsearch 1.7
- PostgreSQL 9.4
<a name="contributing"></a>
## Contributing
Contributions are welcome. Please read [the contribution guidelines](CONTRIBUTING.md) for more information about the contribution process.
**IMPORTANT**: **do not** update Arshaw/fullCalendar.js as it contains a hack for the remove-event cross.
<a name="setup-a-development-environment"></a>
## Setup a development environment
<a name="general-guidelines"></a>
### General Guidelines
1. Install RVM with the ruby version specified in the [.ruby-version file](.ruby-version).
For more details about the process, Please read the [official RVM documentation](http://rvm.io/rvm/install).
2. Retrieve the project from Git
```bash
git clone https://github.com/LaCasemate/fab-manager.git
```
3. Install the software dependencies.
- For Ubuntu/Debian:
```bash
sudo apt-get install libpq-dev postgresql-9.4 redis-server imagemagick
```
- For MacOS X:
```bash
brew install postgresql redis imagemagick
```
4. Init the RVM instance and check it was correctly configured
```bash
cd fab-manager
rvm current
# Must print ruby-X.Y.Z@fablab (where X.Y.Z match the version in .ruby-version)
```
5. Install bundler in the current RVM gemset
```bash
gem install bundler
```
6. Install the required ruby gems
```bash
bundle install
```
7. Build the database. You may have to follow the steps described in [the PostgreSQL installation chapter](#postgresql) before, if you don't already have a working installation of PostgreSQL.
```bash
rake db:setup
```
8. Create the pids folder used by Sidekiq. If you want to use a different location, you can configure it in `config/sidekiq.yml`
```bash
mkdir -p tmp/pids
```
9. Create the default configuration file **and configure it !** (see the [Environment Configuration](#environment-configuration) section)
```bash
cp config/application.yml.default config/application.yml
vi config/application.yml
# or use your favorite editor instead of vi (nano, ne...)
```
10. Start the development web server
```bash
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:
- user: admin@fab-manager.com
- password: adminadmin
<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.
#### POSTGRES_HOST
DNS name or IP address of the server hosting the PostgreSQL database of the application (see [PostgreSQL](#postgresql)).
#### POSTGRES_PASSWORD
Password for the PostgreSQL user, as specified in `database.yml`.
Please see [Setup the FabManager database in PostgreSQL](#setup-fabmanager-in-postgresql) for informations on how to create a user and set his password.
#### REDIS_HOST
DNS name or IP address of the server hosting the redis database.
#### ELASTICSEARCH_HOST
DNS name or IP address of the server hosting the elasticSearch database.
#### SECRET_KEY_BASE
Used by the authentication system to generate random tokens, eg. for resetting passwords.
Used by Rails to generate the integrity of signed cookies.
You can generate such a random key by running `rake secret`.
#### STRIPE_API_KEY & STRIPE_PUBLISHABLE_KEY
Key an secret used to identify you Stripe account through the API.
Retrieve them from https://dashboard.stripe.com/account/apikeys.
#### STRIPE_CURRENCY
Currency used by stripe to charge the final customer.
See https://support.stripe.com/questions/which-currencies-does-stripe-support for a list of available 3-letters ISO code.
#### INVOICE_PREFIX
When payments are done on the platform, an invoice will be generate as a PDF file.
This value configure the prefix of the PDF file name.
#### FABLAB_WITHOUT_PLANS
If set to 'true', the subscription plans will be fully disabled and invisible in the application.
#### DEFAULT_MAIL_FROM
When sending notification mails, the platform will use this address to identify the sender.
#### DELIVERY_METHOD
Configure the Rails' Action Mailer delivery method.
See http://guides.rubyonrails.org/action_mailer_basics.html#action-mailer-configuration for more details.
#### DEFAULT_HOST, DEFAULT_PROTOCOL, SMTP_ADDRESS, SMTP_PORT, SMTP_USER_NAME & SMTP_PASSWORD
When DELIVERY_METHOD is set to **smtp**, configure the SMTP server parameters.
See http://guides.rubyonrails.org/action_mailer_basics.html#action-mailer-configuration for more details.
DEFAULT_HOST is also used to configure Google Analytics.
#### GA_ID
Identifier of your Google Analytics account.
#### DISQUS_SHORTNAME
Unique identifier of your [Disqus](http://www.disqus.com) forum.
Disquq forums are used to allow visitors to comment on projects.
See https://help.disqus.com/customer/portal/articles/466208-what-s-a-shortname- for more informations.
#### TWITTER_NAME
Identifier of the Twitter account, for witch the last tweet will be displayed on the home page.
#### TWITTER_CONSUMER_KEY, TWITTER_CONSUMER_SECRET, TWITTER_ACCESS_TOKEN & TWITTER_ACCESS_TOKEN_SECRET
Keys and secrets to access the twitter API.
#### Settings related to i18n
See the [Settings](#i18n-settings) section of the [Internationalization (i18n)](#i18n) paragraph for a detailed description of these parameters.
<a name="postgresql"></a>
## PostgreSQL
<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 the following lines:
- `deb http://apt.postgresql.org/pub/repos/apt/ trusty-pgdg main` (Ubuntu 14.04 Trusty)
- `deb http://apt.postgresql.org/pub/repos/apt/ jessie-pgdg main` (Debian 8 Jessie)
2. Import the repository signing key, and update the package lists
```bash
wget --quiet -O - https://www.postgresql.org/media/keys/ACCC4CF8.asc | sudo apt-key add -
sudo apt-get update
```
3. Install PostgreSQL 9.4
```bash
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](http://brew.sh/) installed on your system.
Otherwise, please follow the official instructions on the project's website.
1. Update brew and install PostgreSQL
```bash
brew update
brew install postgres
```
2. Launch PostgreSQL
```bash
# 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:setup`, you have to make sure that the user configured in [config/database.yml](config/database.yml) for the `development` environment exists.
To create it, please follow these instructions:
1. Login as the postgres user
```bash
sudo -i -u postgres
```
2. Run the PostgreSQL administration command line interface
```bash
psql
```
3. Create a new user in PostgreSQL (in this example, the user will be named `sleede`)
```sql
CREATE USER sleede;
```
4. Grant him the right to create databases
```sql
ALTER ROLE sleede WITH CREATEDB;
```
5. Then, create the fablab_development and fablab_test databases
```sql
CREATE DATABASE fablab_development OWNER sleede;
CREATE DATABASE fablab_test OWNER sleede;
```
6. To finish, attribute a password to this user
```sql
ALTER USER sleede WITH ENCRYPTED PASSWORD 'sleede';
```
<a name="elasticsearch"></a>
## ElasticSearch
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](https://www.elastic.co/guide/en/elasticsearch/reference/current/setup.html)
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.
```bash
sudo apt-get install openjdk-8-jre
```
1. Create the file `/etc/apt/sources.list.d/elasticsearch-1.x.list`, and append it the following line:
`deb http://packages.elastic.co/elasticsearch/1.x/debian stable main`
2. Import the repository signing key, and update the package lists
```bash
wget -qO - https://packages.elastic.co/GPG-KEY-elasticsearch | sudo apt-key add -
sudo apt-get update
```
3. Install ElasticSearch 1.7
```bash
sudo apt-get install elasticsearch
```
4. 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), you will need to run:
```bash
# System V
sudo update-rc.d elasticsearch defaults 95 10
# *** OR *** (systemd)
sudo /bin/systemctl daemon-reload
sudo /bin/systemctl enable elasticsearch.service
```
<a name="elasticsearch-on-macosx"></a>
### Install ElasticSearch on MacOS X
This assumes you have [Homebrew](http://brew.sh/) installed on your system.
Otherwise, please follow the official instructions on the project's website.
```bash
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
```bash
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](config/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 commands in a rails console.
```bash
rails c
```
```ruby
# Here for the 200 last days
200.times.each do |i|
StatisticService.new.generate_statistic({start_date: i.day.ago.beginning_of_day,end_date: i.day.ago.end_of_day})
end
```
<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>
### Translation
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](http://angular-translate.github.io) with some interpolations interpreted by angular.js and other interpreted by [MessageFormat](https://github.com/SlexAxton/messageformat.js/).
**These two kinds of interpolation use a near but different syntax witch SHOULD NOT be confused.**
Please refer to the official [angular-translate documentation](http://angular-translate.github.io/docs/#/guide/14_pluralization) before translating.
<a name="i18n-translation-back"></a>
#### Back-end translations
Back-end translations uses the [Ruby on Rails syntax](http://guides.rubyonrails.org/i18n.html) but some complex interpolations are interpreted by [MessageFormat](https://github.com/format-message/message-format-rb) 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 informations about the sentence to translate.
<a name="i18n-configuration"></a>
### Configuration
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>
#### Settings
##### RAILS_LOCALE
Be sure that `config/locales/rails.XX.yml` exists, where `XX` match your configured rails_locale.
You can find templates of these files at https://github.com/svenfuchs/rails-i18n/tree/rails-4-x/rails/locale.
Be aware that **this file MUST contain the CURRENCY symbol used to generate invoices** (among other things).
Default is **en**.
##### MOMENT_LOCALE
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).
##### SUMMERNOTE_LOCALE
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).
##### ANGULAR_LOCALE
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**.
##### MESSAGEFORMAT_LOCALE
Configure the messageformat.js library, used by angular-translate.
See vendor/assets/components/messageformat/locale/*.js for a list of available locales.
##### FULLCALENDAR_LOCALE
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).
##### ELASTICSEARCH_LANGUAGE_ANALYZER
This configure the language analyzer for indexing and searching in projects with ElasticSearch.
See https://www.elastic.co/guide/en/elasticsearch/reference/1.7/analysis-lang-analyzer.html for a list of available analyzers (check that the doc version match your installed elasticSearch version).
##### TIME_ZONE
In Rails: set Time.zone 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**.
##### WEEK_STARTING_DAY
Configure the first day of the week in your locale zone (generally monday or sunday).
##### D3_DATE_FORMAT
Date format for dates displayed in statistics charts.
See https://github.com/mbostock/d3/wiki/Time-Formatting#format for 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="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 append 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 happens 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.
<a name="related-documentation"></a>
## Related Documentation
- [Ruby 2.2.3](http://ruby-doc.org/core-2.2.3/)
- [Ruby on Rails](http://api.rubyonrails.org)
- [AngularJS](https://docs.angularjs.org/api)
- [Angular-Bootstrap](http://angular-ui.github.io/bootstrap/)
- [ElasticSearch 1.7](https://www.elastic.co/guide/en/elasticsearch/reference/1.7/index.html)
Reference in New Issue View Git Blame Copy Permalink