scinote-eln/scinote-web
1
1
Fork 0
mirror of https://github.com/scinote-eln/scinote-web.git synced 2025-09-07 21:55:20 +08:00
Code Issues Projects Releases Packages Wiki Activity

Change sciNote -> SciNote

Luka Murn 2018-05-28 16:14:27 +02:00
parent 9be495a745
commit 9837935a33
1 changed files with 34 additions and 34 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

68
Setup-guide.md

@ -1,6 +1,6 @@
## Build & run
sciNote is developed in [Ruby on Rails](http://rubyonrails.org/). It also makes use of [Docker](https://www.docker.com/) technology, so the easiest way to run it is inside Docker containers.
SciNote is developed in [Ruby on Rails](http://rubyonrails.org/). It also makes use of [Docker](https://www.docker.com/) technology, so the easiest way to run it is inside Docker containers.
### Prerequisites
@ -10,15 +10,15 @@ sciNote is developed in [Ruby on Rails](http://rubyonrails.org/). It also makes
### Quick start
The following are minimal steps needed to start sciNote in development environment:
The following are minimal steps needed to start SciNote in development environment:
1. Clone this Git repository onto your development machine.
2. Create a file `config/application.yml`. Populate it with mandatory environmental variables (see [environmental variables](#user-content-environmental-variables)).
3. In sciNote folder, run the following command: `make docker`. This can take a while, since Docker must first pull an image from the Internet, and then also install all neccesary Gems required by sciNote.
3. In SciNote folder, run the following command: `make docker`. This can take a while, since Docker must first pull an image from the Internet, and then also install all neccesary Gems required by SciNote.
4. Once the Docker image is created, run `make cli` command. Once inside the running Docker container, run the following commands: `rake db:create` - `rake db:migrate` - `rake db:seed`. This should initialize the database and fill it with (very minimal) seed data.
5. Exit the Docker container by typing `exit`.
6. To start the server, run command `make run`. Wait until the server starts listening on port `3000`.
7. Inside another CLI window (also from sciNote folder), run command `make worker`. This command should start the background worker process which is used by sciNote for a lot of demanding tasks.
7. Inside another CLI window (also from SciNote folder), run command `make worker`. This command should start the background worker process which is used by SciNote for a lot of demanding tasks.
8. Open your favourite browser and navigate to [http://localhost:3000](http://localhost:3000/). Use the seeded administrator account from [seeds.rb](https://github.com/biosistemika/scinote-web/blob/master/db/seeds.rb) to login, or sign up for a new account.
If you need to run server in production please check [this section](#running-inside-docker-containers-in-production-mode-with-docker-compose)
@ -39,29 +39,29 @@ If you need to run server in production please check [this section](#running-ins
4. Run Docker Quickstart Terminal (also described [here](https://docs.docker.com/mac/step_one/)).
5. Inside this terminal, navigate to cloned Git folder.
6. Follow the [Quick Start Guide](#user-content-quick-start) above.
7. When opening sciNote in browser, instead of navigating to `localhost:3000`, navigate to `<docker-machine-ip>:3000` (you can get the docker machine IP by running command `docker-machine ip default`).
7. When opening SciNote in browser, instead of navigating to `localhost:3000`, navigate to `<docker-machine-ip>:3000` (you can get the docker machine IP by running command `docker-machine ip default`).
**Windows XP, Vista, 7, 8**
There is currently no good way to deploy sciNote onto older Windows operating systems. You can run sciNote inside [Docker Machine](https://docs.docker.com/machine/overview/) - the trouble is that Docker Machine is basically a lightweight Linux [VirtualBox](www.virtualbox.org) VM inside which Docker runs, and is very slow (due to nested virtualization), as well as having problems with file system mounting.
There is currently no good way to deploy SciNote onto older Windows operating systems. You can run SciNote inside [Docker Machine](https://docs.docker.com/machine/overview/) - the trouble is that Docker Machine is basically a lightweight Linux [VirtualBox](www.virtualbox.org) VM inside which Docker runs, and is very slow (due to nested virtualization), as well as having problems with file system mounting.
**Windows 10**
On Windows 10, you can use [Docker for Windows](https://docs.docker.com/docker-for-windows/) - this will install Docker inside a Hyper-V container, which is much faster than Docker Machine. We still suggest to ramp-up the VM's memory to at least 4GB though (right click Docker icon in Windows taskbar -> `Settings...` -> `Advanced`).
1. Install latest version of [Docker for Windows](https://docs.docker.com/docker-for-windows/).
2. Check version of docker-compose by running `docker-compose -v` from command prompt. It needs to be at least version `1.9.0` for sciNote docker-compose scripts to work. If you have an older version of docker-compose, download newer version for Windows from [releases repository](https://github.com/docker/compose/releases), and overwrite the `.exe` file of current docker-compose (it should be located in `<docker-install-dir>/Docker/resources/bin` directory).
2. Check version of docker-compose by running `docker-compose -v` from command prompt. It needs to be at least version `1.9.0` for SciNote docker-compose scripts to work. If you have an older version of docker-compose, download newer version for Windows from [releases repository](https://github.com/docker/compose/releases), and overwrite the `.exe` file of current docker-compose (it should be located in `<docker-install-dir>/Docker/resources/bin` directory).
3. Follow the [Quick Start Guide](#user-content-quick-start) above.
> **Important!** As of right now, sciNote does not provide any Windows `make` script (Linux `make` command will not work on Windows), therefore you need to call docker-compose commands directly. See [Makefile](https://github.com/biosistemika/scinote-web/blob/master/Makefile) to inspect which docker-compose calls `make` commands execute.
> **Important!** As of right now, SciNote does not provide any Windows `make` script (Linux `make` command will not work on Windows), therefore you need to call docker-compose commands directly. See [Makefile](https://github.com/biosistemika/scinote-web/blob/master/Makefile) to inspect which docker-compose calls `make` commands execute.
### Docker structure
**For version 1.10.0 and later**
When starting sciNote application in development mode it runs in a Docker container called `scinote_web_development`, which uses volume `scinote_development_files` for storing uploaded files and `scinote_development_bundler` for storing program dependencies. The database runs in a separate container, called `scinote_db_development`. This database container makes use of a persistent volume called `scinote_development_postgres` for storing database files.
When starting SciNote application in development mode it runs in a Docker container called `scinote_web_development`, which uses volume `scinote_development_files` for storing uploaded files and `scinote_development_bundler` for storing program dependencies. The database runs in a separate container, called `scinote_db_development`. This database container makes use of a persistent volume called `scinote_development_postgres` for storing database files.
**For versions prior to 1.10.0**
The main sciNote application runs in a Docker container called web. The database runs in a separate container, called db. This database container makes use of a special, persistent container called dbdata.
The main SciNote application runs in a Docker container called web. The database runs in a separate container, called db. This database container makes use of a special, persistent container called dbdata.
For running application in production please check this [section](#running-inside-docker-containers-in-production-mode-with-docker-compose)
@ -86,7 +86,7 @@ Following commands are available:
## Environmental variables
sciNote reads configuration parameters from system environment parameters. On production servers, this can be simply be system environmental variables, while for development, a file `config/application.yml` can be created to specify those variables.
SciNote reads configuration parameters from system environment parameters. On production servers, this can be simply be system environmental variables, while for development, a file `config/application.yml` can be created to specify those variables.
Below is an example `application.yml` file, which should get the server running; for full reference, check the below table of all available variables.
@ -96,8 +96,8 @@ SECRET_KEY_BASE: "<<secret_key_base>>"
PAPERCLIP_HASH_SECRET: "<<paperclip_hash_secret>>"
# Mailer settings
MAIL_FROM: "Example sciNote Assistant <assistant@yourdomain.com>"
MAIL_REPLYTO: "Example sciNote Assistant <assistant@yourdomain.com>"
MAIL_FROM: "Example SciNote Assistant <assistant@yourdomain.com>"
MAIL_REPLYTO: "Example SciNote Assistant <assistant@yourdomain.com>"
SMTP_ADDRESS: "your.yoursmtp.com"
SMTP_PORT: "25"
SMTP_DOMAIN: "yoursmtp.com"
@ -145,7 +145,7 @@ DELAYED_WORKER_DEFAULT_QUEUE_NAME: "default"
```
The following table describes all available environmental variables for sciNote server.
The following table describes all available environmental variables for SciNote server.
| Variable | Mandatory | Description |
|-------------------------|-----------|-------------|
@ -162,15 +162,15 @@ The following table describes all available environmental variables for sciNote
| S3_HOST_NAME | No* | If storing files on Amazon S3, this must contain the S3 service host name. |
| AWS_REGION | No* | If storing files on Amazon S3, this must contain the AWS region. |
| **Mailer** | | |
| MAIL_FROM | Yes | The **from** address for emails sent from sciNote. |
| MAIL_REPLYTO | Yes | The **reply to** address for emails sent from sciNote. |
| SMTP_ADDRESS | Yes | The server address of the SMTP mailer used for delivering emails generated in sciNote. |
| MAIL_FROM | Yes | The **from** address for emails sent from SciNote. |
| MAIL_REPLYTO | Yes | The **reply to** address for emails sent from SciNote. |
| SMTP_ADDRESS | Yes | The server address of the SMTP mailer used for delivering emails generated in SciNote. |
| SMTP_PORT | Yes | The port of the SMTP server. Defaults to `587`. |
| SMTP_DOMAIN | Yes | The server domain of the SMTP mailer used for delivering emails generated in sciNote. |
| SMTP_USERNAME | Yes | The username for SMTP mailer used for delivering emails generated in sciNote. |
| SMTP_PASSWORD | Yes | The password for SMTP mailer used for delivering emails generated in sciNote. |
| SMTP_DOMAIN | Yes | The server domain of the SMTP mailer used for delivering emails generated in SciNote. |
| SMTP_USERNAME | Yes | The username for SMTP mailer used for delivering emails generated in SciNote. |
| SMTP_PASSWORD | Yes | The password for SMTP mailer used for delivering emails generated in SciNote. |
| SMTP_AUTH_METHOD | no | SMTP auth method to use, 'plain' is default value. MS Exchange might need 'login' auth method.|
| MAIL_SERVER_URL | Yes | The root URL address of the actual sciNote server. This is used in sent emails to redirect user to the correct sciNote server URL. Defaults to `localhost`. |
| MAIL_SERVER_URL | Yes | The root URL address of the actual SciNote server. This is used in sent emails to redirect user to the correct SciNote server URL. Defaults to `localhost`. |
| **Sign-up process** | | |
| NEW_TEAM_ON_SIGNUP | No | Enables the creation of new team on sign up. If set `false` no team will be created on sign up. Defaults to `true`. |
| ENABLE_EMAIL_CONFIRMATIONS | No | Whether to require users to confirm the following actions: signing-up, signing-up after being invited, and changing their e-mail. Defaults to `true` on `development` and `production` environments, and to `false` on `test` environment. |
@ -186,7 +186,7 @@ The following table describes all available environmental variables for sciNote
| WOPI_TEST_ENABLED | No* | Whether to enable [testing](http://wopi.readthedocs.io/en/latest/build_test_ship/validator.html) of WOPI integration by opening `.wopitest` files. Defaults to `false`. |
| WOPI_DISCOVERY_URL | No* | If using WOPI, this is the [discovery URL](http://wopi.readthedocs.io/en/latest/discovery.html) provided by Microsoft. |
| WOPI_ENDPOINT_URL | No* | If using WOPI, this is the endpoint URL on which the WOPI API will be available. |
| WOPI_BREADCRUMBS_HOST | No* | If using WOPI, this is the URL of sciNote server to be reachable from Microsoft Office Online. |
| WOPI_BREADCRUMBS_HOST | No* | If using WOPI, this is the URL of SciNote server to be reachable from Microsoft Office Online. |
| USER_SUBDOMAIN | No* | If using WOPI, the only subdomain that will be allowed to access all non-WOPI routes. |
| WOPI_SUBDOMAIN | No* | If using WOPI, the WOPI subdomain. |
| **Delayed worker** | | |
@ -203,7 +203,7 @@ The following table describes all available environmental variables for sciNote
### Running server in production mode
New functionality for running in production mode was introduced with sciNote version 1.10.0. In order to run sciNote application in production inside Docker you'll need the following:
New functionality for running in production mode was introduced with SciNote version 1.10.0. In order to run SciNote application in production inside Docker you'll need the following:
* docker engine (version 1.12.0+),
* docker-compose (version 1.6.0+).
@ -227,9 +227,9 @@ All these volumes will be kept safe in case you delete your Docker containers. R
Background jobs worker will be running in another separate container called `scinote_jobs_production`.
Now (finally), you can start sciNote with the following command: `docker-compose -f ./docker-compose.production.yml up`. Or you can use `docker-compose -f ./docker-compose.production.yml up -d` to start the server in background mode. Please consult `docker-compose` documentation for the rest of supported commands.
Now (finally), you can start SciNote with the following command: `docker-compose -f ./docker-compose.production.yml up`. Or you can use `docker-compose -f ./docker-compose.production.yml up -d` to start the server in background mode. Please consult `docker-compose` documentation for the rest of supported commands.
In short, the sequence of commands to setup sciNote (for fresh install) would be:
In short, the sequence of commands to setup SciNote (for fresh install) would be:
```bash
make config-production
@ -261,13 +261,13 @@ Don't forget to migrate ENV variables from `config/application.yml` into `produc
After all of the above steps are done, you can finally update application files and run DB migrations as described [here](#upgrading-scinote-installation-running-in-production-mode).
### Upgrading sciNote installation running in production mode
### Upgrading SciNote installation running in production mode
After downloading the new version of sciNote application files, the following needs to be done to upgrade a running sciNote instance running in production Docker mode.
After downloading the new version of SciNote application files, the following needs to be done to upgrade a running SciNote instance running in production Docker mode.
**1. Rebuild Docker images**
First of all, you will need to rebuild Docker images using the new version of sciNote. That means that you need to stop the current instance (if it is running), and then run the command `make docker-production`.
First of all, you will need to rebuild Docker images using the new version of SciNote. That means that you need to stop the current instance (if it is running), and then run the command `make docker-production`.
**2. Migrate database data**
@ -281,7 +281,7 @@ After migrations are finished, you can start the application normally with the c
### Delayed jobs
sciNote uses [delayed jobs](https://github.com/tobi/delayed_job) library to do background processing, mostly for the following tasks:
SciNote uses [delayed jobs](https://github.com/tobi/delayed_job) library to do background processing, mostly for the following tasks:
* Sending emails,
* Extracting text from uploaded files (*full-text* search),
* Generating introduction tutorials,
@ -320,15 +320,15 @@ Calling `rake data:clean` will execute both above tasks.
### Notifications
To generate a new system notification that will be sent to all sciNote users, execute `rake notifications:new_system[title, message]`. Title & message can contain `HTML` tags.
To generate a new system notification that will be sent to all SciNote users, execute `rake notifications:new_system[title, message]`. Title & message can contain `HTML` tags.
## Mailer
sciNote needs a configured SMTP mail server to work properly. See [environmental variables](#user-content-environmental-variables) for configuration of the mailer.
SciNote needs a configured SMTP mail server to work properly. See [environmental variables](#user-content-environmental-variables) for configuration of the mailer.
## Office Online integration
sciNote can be integrated with an Office Online Server to enable viewing and edition of documents directly in the browser. To enable this integration using the Microsoft Office Online servers, you will need to join the [Office Cloud Storage Partner Program](https://dev.office.com/programs/officecloudstorage) and set up the `WOPI_*` environment variables.
SciNote can be integrated with an Office Online Server to enable viewing and edition of documents directly in the browser. To enable this integration using the Microsoft Office Online servers, you will need to join the [Office Cloud Storage Partner Program](https://dev.office.com/programs/officecloudstorage) and set up the `WOPI_*` environment variables.
## Deploy onto Heroku
@ -360,7 +360,7 @@ Before pushing to heroku master branch, some environmental variables should be s
### Heroku environmental variables
For deployment of sciNote onto Heroku, additional environmental variables need to be specified.
For deployment of SciNote onto Heroku, additional environmental variables need to be specified.
| Variable | Mandatory | Description |
|--------------------------|-----------|--------------------------------------------------------------------------------------------|
@ -376,4 +376,4 @@ For deployment of sciNote onto Heroku, additional environmental variables need t
## Testing
In current version, only *model* tests are implemented for sciNote. To execute them, call `rake test:models`.
In current version, only *model* tests are implemented for SciNote. To execute them, call `rake test:models`.