diff --git a/README.md b/README.md index 9948f4245..886171eb0 100644 --- a/README.md +++ b/README.md @@ -106,53 +106,7 @@ Developers may find information on how to implement their own authentication pro ## 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: - - Error: - ... - 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 "...". - : ... - 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 [the dedicated section](#run-postgresql-cli) for instructions). - Then, run the following command (replace `sleede` with your test database user, as specified in your database.yml): - - ALTER ROLE sleede WITH SUPERUSER; - - 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: - - ```bash - sudo systemctl restart elasticsearch.service - ``` -- In some cases, the invoices won't be generated. This can be due to the image included in the invoice header not being supported. - To fix this issue, change the image in the administrator interface (manage the invoices / invoices settings). - See [this thread](https://forum.fab-manager.com/t/resolu-erreur-generation-facture/428) for more info. - -- In the excel exports, if the cells expected to contain dates are showing strange numbers, check that you have correctly configured the [EXCEL_DATE_FORMAT](doc/environment.md#EXCEL_DATE_FORMAT) variable. +Before reporting an issue, please check if your issue is not listed in the [know issues](doc/known-issues.md) with its solution. ## Related Documentation diff --git a/doc/development_readme.md b/doc/development_readme.md index a3d3af8f3..afdb92a4e 100644 --- a/doc/development_readme.md +++ b/doc/development_readme.md @@ -44,7 +44,7 @@ This procedure is not easy to follow so if you don't need to write some code for 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. + > 🍏 If you're using MacOS, this is not required. ```bash docker network create --subnet=172.18.0.0/16 fabmanager ``` @@ -96,7 +96,7 @@ This procedure is not easy to follow so if you don't need to write some code for yarn install ``` -12. Create the default configuration files **and configure them!** (see the [environment configuration documentation](doc/environment.md)) +12. Create the default configuration files **and configure them!** (see the [environment configuration documentation](environment.md)) ```bash cp config/database.yml.default config/database.yml @@ -154,7 +154,7 @@ We will use docker to easily install the required version of PostgreSQL. ``` 2. Start the PostgreSQL container. - >  If you're using MacOS, remove the --network and --ip parameters, and add -p 5432:5432. + > 🍏 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 \ @@ -165,10 +165,10 @@ We will use docker to easily install the required version of PostgreSQL. 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. + See [environment.md](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). + Some information about that is available in the [PostgreSQL Readme](postgresql_readme.md). ## ElasticSearch @@ -194,7 +194,7 @@ In FabManager, it is used for the admin's statistics module and to perform searc ``` 3. Start the ElasticSearch container. - >  If you're using MacOS, remove the --network and --ip parameters, and add -p 9200:9200. + > 🍏 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 \ @@ -208,7 +208,7 @@ In FabManager, it is used for the admin's statistics module and to perform searc 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. + See [environment.md](environment.md) for more details. ### Rebuild statistics diff --git a/doc/docker-compose_readme.md b/doc/docker-compose_readme.md index b7b08b334..8b833fdea 100644 --- a/doc/docker-compose_readme.md +++ b/doc/docker-compose_readme.md @@ -1,9 +1,9 @@ -# Install Fabmanager app in production with Docker +# Install Fab-Manager in production with docker-compose -This README tries to describe all the steps to put a fabmanager app into production on a server, based on a solution using Docker and Docker-compose. +This document will guide you through all the steps needed to set up your Fab-Manager app on a production server, based on a solution using Docker and Docker-compose. We recommend DigitalOcean, but these steps will work on any Docker-compatible cloud provider or local server. -In order to make it work, please use the same directories structure as described in this guide in your fabmanager app folder. +In order to make it work, please use the same directories structure as described in this guide in your Fab-Manager app folder. You will need to be root through the rest of the setup. ##### Table of contents @@ -57,7 +57,7 @@ On DigitalOcean, create a Droplet with One-click apps **"Docker on Ubuntu 16.04 This way, Docker and Docker-compose are preinstalled. Choose a datacenter and set the hostname as your domain name. -With other providers, choose a [supported operating system](https://github.com/sleede/fab-manager/blob/master/README.md#software-stack) and install docker on it: +With other providers, choose a [supported operating system](../README.md#software-stack) and install docker on it: - [Debian](https://docs.docker.com/engine/installation/linux/docker-ce/debian/) - [Ubuntu](https://docs.docker.com/engine/installation/linux/docker-ce/ubuntu/) @@ -68,9 +68,9 @@ Then install [Docker Compose](https://docs.docker.com/compose/install/) There are many domain name registrars on the internet, you may choose one that fit your needs. You can find an exhaustive list [on the ICANN website](https://www.icann.org/registrar-reports/accredited-list.html) -1. Once done, buy a domain name on it +1. Once done, buy a domain name on it 2. Replace the IP address of the domain with the IP address of your VPS (This is a DNS record type A) -3. **Do not** try to access your domain name right away, DNS are not aware of the change yet so **WAIT** and be patient. +3. **Do not** try to access your domain name right away, DNS are not aware of the change yet so **WAIT** and be patient. ### Connect through SSH @@ -111,7 +111,7 @@ vi config/env # or use your favorite text editor instead of vi (nano, ne...) ``` You need to carefully configure each variable before starting fab-manager. -Please refer to the [environment configuration documentation](../doc/environment.md) for explanations about those variables. +Please refer to the [environment configuration documentation](environment.md) for explanations about those variables. ### Setup nginx configuration diff --git a/doc/known-issues.md b/doc/known-issues.md new file mode 100644 index 000000000..64ed867c7 --- /dev/null +++ b/doc/known-issues.md @@ -0,0 +1,61 @@ +# Known issues + +This document is listing common known issues. + +> Production issues may also apply to development environments. + +##### Table of contents + +1. [Development](#development) +2. [Production](#production) + + +## Development + +- 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. + +- When running the tests suite with `rake test`, all tests may fail with errors similar to the following: + + Error: + ... + 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 "...". + : ... + 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 [the dedicated section](#run-postgresql-cli) for instructions). + Then, run the following command (replace `sleede` with your test database user, as specified in your database.yml): + + ALTER ROLE sleede WITH SUPERUSER; + + DO NOT do this in a production environment, unless you know what you're doing: this could lead to a serious security issue. + + +## Production + +- Due to a stripe limitation, you won't be able to create plans longer than one year. + +- 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: + + ```bash + sudo systemctl restart elasticsearch.service + ``` + +- In some cases, the invoices won't be generated. This can be due to the image included in the invoice header not being supported. + To fix this issue, change the image in the administrator interface (manage the invoices / invoices settings). + See [this thread](https://forum.fab-manager.com/t/resolu-erreur-generation-facture/428) for more info. + +- In the excel exports, if the cells expected to contain dates are showing strange numbers, check that you have correctly configured the [EXCEL_DATE_FORMAT](environment.md#EXCEL_DATE_FORMAT) variable. diff --git a/doc/translation_readme.md b/doc/translation_readme.md index 17667785f..7607e4b27 100644 --- a/doc/translation_readme.md +++ b/doc/translation_readme.md @@ -61,13 +61,14 @@ Use it to generate a similar localised PNG image which keep the default image si ## Configuration -Locales configurations are made in `config/application.yml`. +In development, locales configurations are made in [config/application.yml](../config/application.yml.default). +In production, locales configuration are made in the [config/env](../docker/env.example) file. If you are in a development environment, your can keep the default values, otherwise, in production, values must be configured carefully. ### Settings -Please refer to the [environment configuration documentation](doc/environment.md#internationalization-settings) +Please refer to the [environment configuration documentation](environment.md#internationalization-settings) ### Applying changes