mirror of
https://github.com/LaCasemate/fab-manager.git
synced 2025-02-19 13:54:25 +01:00
updated and refactored readme
updated instructions to setup a development environment splitted readme into multiple files to improve clarity
This commit is contained in:
parent
f50e45d2de
commit
22ae8d5073
@ -15,6 +15,7 @@
|
||||
- Updated moment-timezone
|
||||
- Added freeCAD files as default allowed extensions
|
||||
- Rake task to sync local users with Stripe
|
||||
- Updated and refactored README
|
||||
- Fix a bug: unable to remove the picture from a training
|
||||
- Fix a bug: no alerts on errors during admin creation
|
||||
- Fix a bug: replaces all Time.now by DateTime.current to prevent time zones issues [Taiga#134]
|
||||
|
308
README.md
308
README.md
@ -10,26 +10,13 @@ FabManager is the Fab Lab management solution. It provides a comprehensive, web-
|
||||
1. [Software stack](#software-stack)
|
||||
2. [Contributing](#contributing)
|
||||
3. [Setup a production environment](#setup-a-production-environment)
|
||||
4. [Setup a development environment](#setup-a-development-environment)<br/>
|
||||
4.1. [General Guidelines](#general-guidelines)<br/>
|
||||
5. [PostgreSQL](#postgresql)<br/>
|
||||
5.1. [Install PostgreSQL 9.6](#setup-postgresql)
|
||||
6. [ElasticSearch](#elasticsearch)<br/>
|
||||
6.1. [Install ElasticSearch](#setup-elasticsearch)<br/>
|
||||
6.2. [Rebuild statistics](#rebuild-stats)<br/>
|
||||
6.3. [Backup and Restore](#backup-and-restore-elasticsearch)
|
||||
7. [Internationalization (i18n)](#i18n)<br/>
|
||||
7.1. [Translation](#i18n-translation)<br/>
|
||||
7.1.1. [Front-end translations](#i18n-translation-front)<br/>
|
||||
7.1.2. [Back-end translations](#i18n-translation-back)<br/>
|
||||
7.2. [Configuration](#i18n-configuration)<br/>
|
||||
7.2.1. [Settings](#i18n-settings)<br/>
|
||||
7.2.2. [Applying changes](#i18n-apply)
|
||||
8. [Open Projects](#open-projects)
|
||||
9. [Plugins](#plugins)
|
||||
10. [Single Sign-On](#sso)
|
||||
11. [Known issues](#known-issues)
|
||||
12. [Related Documentation](#related-documentation)
|
||||
4. [Setup a development environment](#setup-a-development-environment)
|
||||
5. [Internationalization (i18n)](#i18n)
|
||||
6. [Open Projects](#open-projects)
|
||||
7. [Plugins](#plugins)
|
||||
8. [Single Sign-On](#sso)
|
||||
9. [Known issues](#known-issues)
|
||||
10. [Related Documentation](#related-documentation)
|
||||
|
||||
|
||||
|
||||
@ -54,293 +41,22 @@ Contributions are welcome. Please read [the contribution guidelines](CONTRIBUTIN
|
||||
## Setup a production environment
|
||||
|
||||
To run fab-manager as a production application, this is highly recommended to use [Docker-compose](https://docs.docker.com/compose/overview/).
|
||||
The procedure to follow is described in the [docker-compose readme](docker/README.md).
|
||||
The procedure to follow is described in the [docker-compose readme](doc/docker-compose_readme.md).
|
||||
|
||||
<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.
|
||||
In you intend to run fab-manager on your local machine to contribute to the project development, you can set it up by following the [development readme](doc/development_readme.md).
|
||||
This procedure relies on docker to set-up the dependencies.
|
||||
|
||||
This procedure is not easy to follow so if you don't need to write some code for Fab-manager, please prefer the [docker-compose installation method](docker/README.md).
|
||||
|
||||
Optionally, you can use a virtual development environment that relies on Vagrant and Virtual Box by following the [virtual machine instructions](doc/virtual-machine.md).
|
||||
|
||||
<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).
|
||||
If you're using ArchLinux, you may have to [read this](doc/archlinux_readme.md) before.
|
||||
|
||||
2. Install NVM, with the node.js version specified in the [.nvmrc file](.nvmrc).
|
||||
For instructions about installing NVM, please refer to [the NVM readme](https://github.com/creationix/nvm#installation).
|
||||
|
||||
3. Install Yarn, the front-end package manager.
|
||||
Depending on your system, the installation process may differ, please read the [official Yarn documentation](https://yarnpkg.com/en/docs/install#debian-stable).
|
||||
|
||||
4. Install docker.
|
||||
Your system may provide a pre-packaged version of docker in its repositories, but this version may be outdated.
|
||||
Please refer to [ubuntu](https://docs.docker.com/install/linux/docker-ce/ubuntu/), [debian](https://docs.docker.com/install/linux/docker-ce/debian/) or [MacOS](https://docs.docker.com/docker-for-mac/install/) documentation to setup a recent version of docker.
|
||||
|
||||
5. Add your current user to the docker group, to allow using docker without `sudo`.
|
||||
```bash
|
||||
# add the docker group if it doesn't already exist
|
||||
sudo groupadd docker
|
||||
# add the current user to the docker group
|
||||
sudo usermod -aG docker $(whoami)
|
||||
# restart to validate changes
|
||||
sudo reboot
|
||||
```
|
||||
|
||||
6. Create a docker network for fab-manager.
|
||||
You may have to change the network address if it is already in use.
|
||||
```bash
|
||||
docker network create --subnet=172.18.0.0/16 fabmanager
|
||||
```
|
||||
|
||||
7. Retrieve the project from Git
|
||||
|
||||
```bash
|
||||
git clone https://github.com/sleede/fab-manager.git
|
||||
```
|
||||
|
||||
8. Install the software dependencies.
|
||||
First install [PostgreSQL](#postgresql) and [ElasticSearch](#elasticsearch) as specified in their respective documentations.
|
||||
Then install the other dependencies:
|
||||
- For Ubuntu/Debian:
|
||||
|
||||
```bash
|
||||
# on Ubuntu 18.04 server, you may have to enable the "universe" repository
|
||||
sudo add-apt-repository universe
|
||||
# then, install the dependencies
|
||||
sudo apt-get install libpq-dev redis-server imagemagick
|
||||
```
|
||||
- For MacOS X:
|
||||
|
||||
```bash
|
||||
brew install redis imagemagick
|
||||
```
|
||||
|
||||
9. Init the RVM and NVM instances and check they were correctly configured
|
||||
|
||||
```bash
|
||||
cd fab-manager
|
||||
rvm current | grep -q `cat .ruby-version`@fab-manager && echo "ok"
|
||||
# Must print ok
|
||||
nvm use
|
||||
node --version | grep -q `cat .nvmrc` && echo "ok"
|
||||
# Must print ok
|
||||
```
|
||||
|
||||
10. Install bundler in the current RVM gemset
|
||||
|
||||
```bash
|
||||
gem install bundler --version=1.17.3
|
||||
```
|
||||
|
||||
11. Install the required ruby gems and javascript plugins
|
||||
|
||||
```bash
|
||||
bundle install
|
||||
yarn install
|
||||
```
|
||||
|
||||
12. Create the default configuration files **and configure them!** (see the [environment configuration documentation](doc/environment.md))
|
||||
|
||||
```bash
|
||||
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...)
|
||||
```
|
||||
|
||||
13. Build the databases.
|
||||
- **Warning**: **DO NOT** run `rake db:setup` instead of these commands, as this will not run some required raw SQL instructions.
|
||||
- **Please note**: Your password length must be between 8 and 128 characters, otherwise db:seed will be rejected. This is configured in [config/initializers/devise.rb](config/initializers/devise.rb)
|
||||
|
||||
```bash
|
||||
# for dev
|
||||
rake db:create
|
||||
rake db:migrate
|
||||
ADMIN_EMAIL='youradminemail' ADMIN_PASSWORD='youradminpassword' rake db:seed
|
||||
rake fablab:es:build_stats
|
||||
# for tests
|
||||
RAILS_ENV=test rake db:create
|
||||
RAILS_ENV=test rake db:migrate
|
||||
```
|
||||
|
||||
14. 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
|
||||
```
|
||||
|
||||
15. Start the development web server
|
||||
|
||||
```bash
|
||||
foreman s -p 3000
|
||||
```
|
||||
|
||||
16. You should now be able to access your local development FabManager instance by accessing `http://localhost:3000` in your web browser.
|
||||
|
||||
17. You can login as the default administrator using the credentials defined previously.
|
||||
|
||||
18. 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="postgresql"></a>
|
||||
## PostgreSQL
|
||||
|
||||
<a name="setup-postgresql"></a>
|
||||
### Install PostgreSQL 9.6
|
||||
|
||||
We will use docker to easily install the required version of PostgreSQL.
|
||||
|
||||
1. Create the docker binding folder
|
||||
```bash
|
||||
mkdir -p .docker/postgresql
|
||||
```
|
||||
|
||||
2. Start the PostgreSQL container.
|
||||
```bash
|
||||
docker run --restart=always -d --name fabmanager-postgres \
|
||||
-v $(pwd)/.docker/postgresql:/var/lib/postgresql/data \
|
||||
--network fabmanager --ip 172.18.0.2 \
|
||||
-p 5432:5432 \
|
||||
postgres:9.6
|
||||
```
|
||||
|
||||
3. Configure fab-manager to use it.
|
||||
On linux systems, PostgreSQL will be available at 172.18.0.2.
|
||||
On MacOS, you'll have to set the host to 127.0.0.1 (or localhost).
|
||||
See [environment.md](doc/environment.md) for more details.
|
||||
|
||||
4 . Finally, you may want to have a look at detailed informations about PostgreSQL usage in fab-manager.
|
||||
Some information about that is available in the [PostgreSQL Readme](doc/postgresql_readme.md).
|
||||
|
||||
<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="setup-elasticsearch"></a>
|
||||
### Install ElasticSearch
|
||||
|
||||
1. Create the docker binding folders
|
||||
```bash
|
||||
mkdir -p .docker/elasticsearch/config
|
||||
mkdir -p .docker/elasticsearch/plugins
|
||||
mkdir -p .docker/elasticsearch/backups
|
||||
```
|
||||
|
||||
2. Copy the default configuration files
|
||||
```bash
|
||||
cp docker/elasticsearch.yml .docker/elasticsearch/config
|
||||
cp docker/log4j2.properties .docker/elasticsearch/config
|
||||
```
|
||||
|
||||
3. Start the ElasticSearch container.
|
||||
```bash
|
||||
docker run --restart=always -d --name fabmanager-elastic \
|
||||
-v $(pwd)/.docker/elasticsearch/config:/usr/share/elasticsearch/config \
|
||||
-v $(pwd)/.docker/elasticsearch:/usr/share/elasticsearch/data \
|
||||
-v $(pwd)/.docker/elasticsearch/plugins:/usr/share/elasticsearch/plugins \
|
||||
-v $(pwd)/.docker/elasticsearch/backups:/usr/share/elasticsearch/backups \
|
||||
--network fabmanager --ip 172.18.0.3 \
|
||||
-p 9200:9200 -p 9300:9300 \
|
||||
elasticsearch:5.6
|
||||
```
|
||||
|
||||
4. Configure fab-manager to use it.
|
||||
On linux systems, ElasticSearch will be available at 172.18.0.3.
|
||||
On MacOS, you'll have to set the host to 127.0.0.1 (or localhost).
|
||||
See [environment.md](doc/environment.md) for more details.
|
||||
|
||||
<a name="rebuild-stats"></a>
|
||||
### Rebuild statistics
|
||||
|
||||
Every nights, the statistics for the day that just ended are built automatically at 01:00 (AM) and stored in ElastricSearch.
|
||||
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 command.
|
||||
|
||||
```bash
|
||||
# Here for the 50 last days
|
||||
rake fablab:es:generate_stats[50]
|
||||
```
|
||||
|
||||
<a name="backup-and-restore-elasticsearch"></a>
|
||||
### Backup and Restore
|
||||
|
||||
To backup and restore the ElasticSearch database, use the [elasticsearch-dump](https://github.com/taskrabbit/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`.
|
||||
Optionally, you can use a virtual development environment that relies on Vagrant and Virtual Box by following the [virtual machine instructions](virtual-machine.md).
|
||||
|
||||
<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 which 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 information about the sentence to translate.
|
||||
|
||||
You will also need to translate the invoice watermark, located in `app/pdfs/data/`.
|
||||
You'll find there the [GIMP source of the image](app/pdfs/data/watermark.xcf), which is using [Rubik Mono One](https://fonts.google.com/specimen/Rubik+Mono+One) as font.
|
||||
Use it to generate a similar localised PNG image which keep the default image size, as PDF are not responsive.
|
||||
|
||||
|
||||
<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
|
||||
|
||||
Please refer to the [environment configuration documentation](doc/environment.md#internationalization-settings)
|
||||
|
||||
<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.
|
||||
Please refer to the [translation readme](doc/translation_readme.md) for instructions about configuring the language or to contribute to the translation.
|
||||
|
||||
<a name="open-projects"></a>
|
||||
## Open Projects
|
||||
|
231
doc/development_readme.md
Normal file
231
doc/development_readme.md
Normal file
@ -0,0 +1,231 @@
|
||||
# Install Fab-Manager in a development environment with Docker
|
||||
|
||||
This document will guide you through all the steps needed to set up a development environment for Fab-Manager.
|
||||
|
||||
##### Table of contents
|
||||
|
||||
1. [General Guidelines](#general-guidelines)<br/>
|
||||
2. [PostgreSQL](#postgresql)<br/>
|
||||
2.1. [Install PostgreSQL 9.6](#setup-postgresql)
|
||||
3. [ElasticSearch](#elasticsearch)<br/>
|
||||
3.1. [Install ElasticSearch](#setup-elasticsearch)<br/>
|
||||
3.2. [Rebuild statistics](#rebuild-stats)<br/>
|
||||
3.3. [Backup and Restore](#backup-and-restore-elasticsearch)
|
||||
|
||||
This procedure is not easy to follow so if you don't need to write some code for Fab-manager, please prefer the [docker-compose installation method](docker-compose_readme.md).
|
||||
|
||||
|
||||
<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).
|
||||
If you're using ArchLinux, you may have to [read this](archlinux_readme.md) before.
|
||||
|
||||
2. Install NVM, with the node.js version specified in the [.nvmrc file](../.nvmrc).
|
||||
For instructions about installing NVM, please refer to [the NVM readme](https://github.com/nvm-sh/nvm#installation-and-update).
|
||||
|
||||
3. Install Yarn, the front-end package manager.
|
||||
Depending on your system, the installation process may differ, please read the [official Yarn documentation](https://yarnpkg.com/en/docs/install#debian-stable).
|
||||
|
||||
4. Install docker.
|
||||
Your system may provide a pre-packaged version of docker in its repositories, but this version may be outdated.
|
||||
Please refer to [ubuntu](https://docs.docker.com/install/linux/docker-ce/ubuntu/), [debian](https://docs.docker.com/install/linux/docker-ce/debian/) or [MacOS](https://docs.docker.com/docker-for-mac/install/) documentation to setup a recent version of docker.
|
||||
|
||||
5. Add your current user to the docker group, to allow using docker without `sudo`.
|
||||
```bash
|
||||
# add the docker group if it doesn't already exist
|
||||
sudo groupadd docker
|
||||
# add the current user to the docker group
|
||||
sudo usermod -aG docker $(whoami)
|
||||
# restart to validate changes
|
||||
sudo reboot
|
||||
```
|
||||
|
||||
6. Create a docker network for fab-manager.
|
||||
You may have to change the network address if it is already in use.
|
||||
> If you're using MacOS, this is not required.
|
||||
```bash
|
||||
docker network create --subnet=172.18.0.0/16 fabmanager
|
||||
```
|
||||
|
||||
7. Retrieve the project from Git
|
||||
|
||||
```bash
|
||||
git clone https://github.com/sleede/fab-manager.git
|
||||
```
|
||||
|
||||
8. Install the software dependencies.
|
||||
First install [PostgreSQL](#postgresql) and [ElasticSearch](#elasticsearch) as specified in their respective documentations (see below).
|
||||
Then install the other dependencies:
|
||||
- For Ubuntu/Debian:
|
||||
|
||||
```bash
|
||||
# on Ubuntu 18.04 server, you may have to enable the "universe" repository
|
||||
sudo add-apt-repository universe
|
||||
# then, install the dependencies
|
||||
sudo apt-get install libpq-dev redis-server imagemagick
|
||||
```
|
||||
- For MacOS X:
|
||||
|
||||
```bash
|
||||
brew install redis imagemagick
|
||||
```
|
||||
|
||||
9. Init the RVM and NVM instances and check they were correctly configured
|
||||
|
||||
```bash
|
||||
cd fab-manager
|
||||
rvm current | grep -q `cat .ruby-version`@fab-manager && echo "ok"
|
||||
# Must print ok
|
||||
nvm use
|
||||
node --version | grep -q `cat .nvmrc` && echo "ok"
|
||||
# Must print ok
|
||||
```
|
||||
|
||||
10. Install bundler in the current RVM gemset
|
||||
|
||||
```bash
|
||||
gem install bundler --version=1.17.3
|
||||
```
|
||||
|
||||
11. Install the required ruby gems and javascript plugins
|
||||
|
||||
```bash
|
||||
bundle install
|
||||
yarn install
|
||||
```
|
||||
|
||||
12. Create the default configuration files **and configure them!** (see the [environment configuration documentation](doc/environment.md))
|
||||
|
||||
```bash
|
||||
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...)
|
||||
```
|
||||
|
||||
13. Build the databases.
|
||||
- **Warning**: **DO NOT** run `rake db:setup` instead of these commands, as this will not run some required raw SQL instructions.
|
||||
- **Please note**: Your password length must be between 8 and 128 characters, otherwise db:seed will be rejected. This is configured in [config/initializers/devise.rb](config/initializers/devise.rb)
|
||||
|
||||
```bash
|
||||
# for dev
|
||||
rake db:create
|
||||
rake db:migrate
|
||||
ADMIN_EMAIL='youradminemail' ADMIN_PASSWORD='youradminpassword' rake db:seed
|
||||
rake fablab:es:build_stats
|
||||
# for tests
|
||||
RAILS_ENV=test rake db:create
|
||||
RAILS_ENV=test rake db:migrate
|
||||
```
|
||||
|
||||
14. 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
|
||||
```
|
||||
|
||||
15. Start the development web server
|
||||
|
||||
```bash
|
||||
foreman s -p 3000
|
||||
```
|
||||
|
||||
16. You should now be able to access your local development FabManager instance by accessing `http://localhost:3000` in your web browser.
|
||||
|
||||
17. You can login as the default administrator using the credentials defined previously.
|
||||
|
||||
18. 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="postgresql"></a>
|
||||
## PostgreSQL
|
||||
|
||||
<a name="setup-postgresql"></a>
|
||||
### Install PostgreSQL 9.6
|
||||
|
||||
We will use docker to easily install the required version of PostgreSQL.
|
||||
|
||||
1. Create the docker binding folder
|
||||
```bash
|
||||
mkdir -p .docker/postgresql
|
||||
```
|
||||
|
||||
2. Start the PostgreSQL container.
|
||||
> If you're using MacOS, remove the --network and --ip parameters, and add -p 5432:5432.
|
||||
```bash
|
||||
docker run --restart=always -d --name fabmanager-postgres \
|
||||
-v $(pwd)/.docker/postgresql:/var/lib/postgresql/data \
|
||||
--network fabmanager --ip 172.18.0.2 \
|
||||
postgres:9.6
|
||||
```
|
||||
|
||||
3. Configure fab-manager to use it.
|
||||
On linux systems, PostgreSQL will be available at 172.18.0.2.
|
||||
On MacOS, you'll have to set the host to 127.0.0.1 (or localhost).
|
||||
See [environment.md](doc/environment.md) for more details.
|
||||
|
||||
4 . Finally, you may want to have a look at detailed informations about PostgreSQL usage in fab-manager.
|
||||
Some information about that is available in the [PostgreSQL Readme](doc/postgresql_readme.md).
|
||||
|
||||
<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="setup-elasticsearch"></a>
|
||||
### Install ElasticSearch
|
||||
|
||||
1. Create the docker binding folders
|
||||
```bash
|
||||
mkdir -p .docker/elasticsearch/config
|
||||
mkdir -p .docker/elasticsearch/plugins
|
||||
mkdir -p .docker/elasticsearch/backups
|
||||
```
|
||||
|
||||
2. Copy the default configuration files
|
||||
```bash
|
||||
cp docker/elasticsearch.yml .docker/elasticsearch/config
|
||||
cp docker/log4j2.properties .docker/elasticsearch/config
|
||||
```
|
||||
|
||||
3. Start the ElasticSearch container.
|
||||
> If you're using MacOS, remove the --network and --ip parameters, and add -p 9200:9200.
|
||||
```bash
|
||||
docker run --restart=always -d --name fabmanager-elastic \
|
||||
-v $(pwd)/.docker/elasticsearch/config:/usr/share/elasticsearch/config \
|
||||
-v $(pwd)/.docker/elasticsearch:/usr/share/elasticsearch/data \
|
||||
-v $(pwd)/.docker/elasticsearch/plugins:/usr/share/elasticsearch/plugins \
|
||||
-v $(pwd)/.docker/elasticsearch/backups:/usr/share/elasticsearch/backups \
|
||||
--network fabmanager --ip 172.18.0.3 \
|
||||
elasticsearch:5.6
|
||||
```
|
||||
|
||||
4. Configure fab-manager to use it.
|
||||
On linux systems, ElasticSearch will be available at 172.18.0.3.
|
||||
On MacOS, you'll have to set the host to 127.0.0.1 (or localhost).
|
||||
See [environment.md](doc/environment.md) for more details.
|
||||
|
||||
<a name="rebuild-stats"></a>
|
||||
### Rebuild statistics
|
||||
|
||||
Every nights, the statistics for the day that just ended are built automatically at 01:00 (AM) and stored in ElastricSearch.
|
||||
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 command.
|
||||
|
||||
```bash
|
||||
# Here for the 50 last days
|
||||
rake fablab:es:generate_stats[50]
|
||||
```
|
||||
|
||||
<a name="backup-and-restore-elasticsearch"></a>
|
||||
### Backup and Restore
|
||||
|
||||
To backup and restore the ElasticSearch database, use the [elasticsearch-dump](https://github.com/taskrabbit/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`.
|
75
doc/translation_readme.md
Normal file
75
doc/translation_readme.md
Normal file
@ -0,0 +1,75 @@
|
||||
# Fab-Manager translation documentation
|
||||
|
||||
This document will explain you what you need to know to contribute to the translation process of Fab-Manager.
|
||||
|
||||
##### Table of contents
|
||||
|
||||
1. [Translation](#i18n-translation)<br/>
|
||||
1.1. [Front-end translations](#i18n-translation-front)<br/>
|
||||
1.2. [Back-end translations](#i18n-translation-back)
|
||||
2. [Configuration](#i18n-configuration)<br/>
|
||||
2.1. [Settings](#i18n-settings)<br/>
|
||||
2.2. [Applying changes](#i18n-apply)
|
||||
|
||||
<a name="i18n-translation"></a>
|
||||
## Translation
|
||||
|
||||
First, consider that it can be a good idea to setup a development environment to contribute to the software translation.
|
||||
This is not mandatory, but this will allow you to test your changes in context and see if anything went wrong, especially with the special syntaxes.
|
||||
Please refer to the [development readme](development_readme.md) or to the [virtual machine instructions](virtual-machine.md) to setup such an environment.
|
||||
|
||||
Once done, 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 which support syntax coloration for YML and Ruby.
|
||||
As an example, [Visual Studio Code](https://code.visualstudio.com/), with the [Ruby extension](https://marketplace.visualstudio.com/items?itemName=rebornix.Ruby) and the [YAML extension](https://marketplace.visualstudio.com/items?itemName=redhat.vscode-yaml) will do the job.
|
||||
|
||||
<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 information about the sentence to translate.
|
||||
|
||||
You will also need to translate the invoice watermark, located in `app/pdfs/data/`.
|
||||
You'll find there the [GIMP source of the image](app/pdfs/data/watermark.xcf), which is using [Rubik Mono One](https://fonts.google.com/specimen/Rubik+Mono+One) as font.
|
||||
Use it to generate a similar localised PNG image which keep the default image size, as PDF are not responsive.
|
||||
|
||||
|
||||
<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
|
||||
|
||||
Please refer to the [environment configuration documentation](doc/environment.md#internationalization-settings)
|
||||
|
||||
<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.
|
Loading…
x
Reference in New Issue
Block a user