mirror of
https://github.com/scinote-eln/scinote-web.git
synced 2024-09-20 23:16:15 +08:00
190 lines
12 KiB
Markdown
190 lines
12 KiB
Markdown
# sciNote
|
|
|
|
|
|
|
|
## About
|
|
|
|
sciNote is an open source electronic lab notebook ([ELN](https://en.wikipedia.org/wiki/Electronic_lab_notebook)) that helps you manage your laboratory work and stores all your experimental data in one place. sciNote is specifically designed for life science students, researchers, lab technicians and group leaders.
|
|
|
|
## 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.
|
|
|
|
### Quick start
|
|
|
|
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.
|
|
4. Once the Docker image is created, run `make cli` command. Once inside the running Docker container, run the following command: `rake db:reset`. 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. Open your favourite browser and navigate to [http://localhost:3000](http://localhost:3000/). Use the seeded administrator account from [seeds.rb](db/seeds.rb) to login, or sign up for a new account.
|
|
|
|
### OS-specific Install Instructions
|
|
|
|
**Debian**
|
|
|
|
1. Install Docker and add user `1000` to the docker group as described [here](https://docs.docker.com/engine/installation/linux/debian/).
|
|
2. Install Docker Compose as described [here](https://docs.docker.com/compose/install/).
|
|
3. Follow [Quick Start Guide](#user-content-quick-start) above as user `1000`.
|
|
|
|
**Mac OS X**
|
|
|
|
1. Install command line developer tools (there are many resources online, like [this](http://osxdaily.com/2014/02/12/install-command-line-tools-mac-os-x/)).
|
|
2. Install Docker Toolbox as described [here](https://docs.docker.com/mac/step_one/).
|
|
3. Inside CLI, run `git clone https://github.com/biosistemika/scinote-web.git`.
|
|
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`).
|
|
|
|
### Docker structure
|
|
|
|
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`.
|
|
|
|
### Commands
|
|
|
|
Call `make` commands to build Docker images and build Rails environment, including database.
|
|
|
|
Following commands are available:
|
|
|
|
| Command | Description |
|
|
|----------------|-------------------------------------------------------------------------------------------------|
|
|
| `make docker` | Downloads the Docker image and build Gems. This should be called whenever `Gemfile` is changed. |
|
|
| `make db-cli` | Runs a `/bin/bash` inside the `db` container. |
|
|
| `make run` | Runs the `db` container & starts the Rails server in `web` container. |
|
|
| `make start` | Runs the `db` container & starts the Rails server in `web` container in background. |
|
|
| `make stop` | Stops the `db` & `web` containers. |
|
|
| `make cli` | Runs a `/bin/bash` inside the `web` container. |
|
|
| `make tests` | Execute all Rails tests. |
|
|
| `make console` | Enters the Rails console in `web` container. |
|
|
| `make export` | Zips the head of this Git repository into a `.tar.gz` file. |
|
|
|
|
## 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.
|
|
|
|
The following table describes all available environmental variables for sciNote server.
|
|
|
|
| Variable | Mandatory | Description |
|
|
|-------------------------|-----------|-------------|
|
|
| SECRET_KEY_BASE | Yes | Random hash for Rails encryption. Can be generated by running `rake secret`. |
|
|
| PAPERCLIP_STORAGE | Yes | Set to `'s3'` to store files on Amazon S3, or `'filesystem'` to store files on local server. If storing on S3, additional parameters need to be specified. |
|
|
| AWS_SECRET_ACCESS_KEY | No* | If storing files on Amazon S3, this must contain access key for accessing AWS S3 API. |
|
|
| AWS_ACCESS_KEY_ID | No* | If storing files on Amazon S3, this must contain access key ID for AWS S3. |
|
|
| S3_BUCKET | No* | If storing files on Amazon S3, this must contain S3 bucket on which files are stored. |
|
|
| AWS_REGION | No* | If storing files on Amazon S3, this must contain the AWS region. |
|
|
| PAPERCLIP_DIRECT_UPLOAD | No* | If storing files on Amazon S3, this must be set either to `1` (to upload files directly from client-side to S3, without passing through sciNote server) or to `0` (to upload files to S3 through sciNote server). |
|
|
| 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. |
|
|
| 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`. |
|
|
| PAPERCLIP_HASH_SECRET | Yes | Random key for generating Paperclip hash key for URLs. Can be generated via following Ruby function: `SecureRandom.base64(128)`. |
|
|
| ENABLE_TUTORIAL | Yes | Whether to display tutorial (and auto-generate demo project) to first-time users. Defaults to `false` on development, and to `true` on production. |
|
|
|
|
## Rake tasks
|
|
|
|
### Delayed jobs
|
|
|
|
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).
|
|
|
|
Best option to run delayed jobs is inside a worker process. To start a background worker process that will execute delayed jobs, run the following command:
|
|
```
|
|
rake jobs:work
|
|
```
|
|
To clear all currently queued jobs, you can use the following command:
|
|
```
|
|
rake jobs:clear
|
|
```
|
|
**Warning!** This is not advised to do on production environments.
|
|
|
|
### Adding users
|
|
|
|
To simplify adding of new users to the system, couple of special `rake` tasks have been created.
|
|
|
|
The first, `rake db:add_user` simply queries all the information for a specific user via STDIN, and then proceeds to create the user.
|
|
|
|
The second task, `rake db:load_users[file_path,create_orgs]` takes 2 parameters as an input:
|
|
* Path to `.yml` file containing list of users & organizations to be added. The YAML file needs to be structured properly - field names must match those in the database, users need to have a name `user_<id>`, and organizations name `org_<id>`. For an example load users file, see [db/load_users_template.yml](db/load_users_template.yml) file.
|
|
* A boolean ('true' or 'false') whether to create individual organizations for each user or not.
|
|
|
|
Both of those rake actions include all database operations inside a transaction, so as long as any error happens during the process, database will be unaffected.
|
|
|
|
### Generating fake data
|
|
|
|
For testing purposes, two special tasks that will populate the database with randomized, fake data, have been implemented.
|
|
|
|
The first, `rake db:fake:generate`, will add fake data to an existing database. Since the algorithm that generates randomized data relies heavily on querying existing entries in database, use of this task is **not advisable**.
|
|
|
|
It is **much better** to use `rake db:fake` task, that will drop the database first, recreate it, and populate it with fake data afterwards.
|
|
|
|
### Web statistics
|
|
|
|
To check current login statistics of registered users, use `rake web_stats:login` task.
|
|
|
|
### Clearing data
|
|
|
|
Execute `rake data:clean_temp_files` to remove all temporary files. Temporary files are used when importing samples.
|
|
Execute `rake data:clean_unconfirmed_users` to remove all users that registered, but never confirmed their email.
|
|
Calling `rake data:clean` will execute both above tasks.
|
|
|
|
## Mailer
|
|
|
|
sciNote needs a configured SMTP mail server to work properly. See [environmental variables](#user-content-environmental-variables) for configuration of the mailer.
|
|
|
|
## Deploy onto Heroku
|
|
|
|
Before deploying to Heroku, install heroku client as describe on offical website. To use existing heroku application, add new git remote repository.
|
|
|
|
```
|
|
git remote add heroku git@heroku.com:my-random-app-name.git
|
|
```
|
|
|
|
Or create new heroku application by executing following command.
|
|
|
|
```
|
|
heroku create
|
|
```
|
|
|
|
Before pushing to heroku master branch, some environmental variables should be set.
|
|
|
|
### Heroku environmental variables
|
|
|
|
For deployment of sciNote onto Heroku, additional environmental variables need to be specified.
|
|
|
|
| Variable | Mandatory | Description |
|
|
|--------------------------|-----------|--------------------------------------------------------------------------------------------|
|
|
| SKYLIGHT_AUTHENTICATION | No | The API key for [Skylight](https://www.skylight.io/) code profiler, if choosing to use it. |
|
|
| LANG | Yes | The default localization language (e.g. `en_US.UTF-8`). |
|
|
| RAILS_ENV | Yes | Rails environment: `production`, `test` or `development`. |
|
|
| RACK_ENV | Yes | Rack environment: `production`, `test` or `development`. |
|
|
| RAILS_SERVE_STATIC_FILES | Yes | Whether to serve static files. Must be set to `enabled`. |
|
|
| WEB_CONCURRENCY | Yes | The concurrency of the server. See Heroku specifications for details. |
|
|
| MAX_THREADS | Yes | The max. number of threads. See Heroku specifications for details. |
|
|
| PORT | Yes | The port on which the application should run. See Heroku specifications for details. |
|
|
| S3_HOST_NAME | No* | If storing files on Amazon S3, this must contain the S3 service host name. |
|
|
| RAILS_FORCE_SSL | Yes | If set to `1`, enforce SSL communication on all levels of application. |
|
|
| DATABASE_URL | Yes | Full URL for connecting to PostgreSQL database. |
|
|
|
|
## Testing
|
|
|
|
In current version, only *model* tests are implemented for sciNote. To execute them, call `rake test:models`.
|
|
|
|
## Contributing
|
|
|
|
For contributing, see [CONTRIBUTING.md](CONTRIBUTING.md).
|
|
|
|
## License
|
|
|
|
sciNote is developed and maintained by BioSistemika USA, LLC, under [Mozilla Public License Version 2.0](LICENSE.txt).
|
|
|
|
See [LICENSE-3RD-PARTY.txt](LICENSE-3RD-PARTY.txt) for licenses of included third-party libraries.
|