-
Notifications
You must be signed in to change notification settings - Fork 2
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Refact(doc): update installation method
Add emphasis on Docker image to run the game.
- Loading branch information
1 parent
191c440
commit 7aca914
Showing
1 changed file
with
54 additions
and
114 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -18,145 +18,86 @@ The `README` file is available at [https://sourcesup.renater.fr/plantbreedgame/] | |
| # Example | ||
|
|
||
| You can discover an example online [here](http://www.agap-sunshine.inra.fr/breeding-game/). | ||
| But if you want to install the game on your own computer or server, read on! | ||
|
|
||
| # Installation | ||
|
|
||
| > Note: for nix users, a flake is available in this repository (cf. [Nix](#Nix-snowflake) section) | ||
| The recomended way to run this web application is by using its [Docker](https://www.docker.com/) image. | ||
|
|
||
| ## Dependencies | ||
| Before running the game make sure to install a recent version of Docker on your system. To install Docker please refer to [their official documentation](https://docs.docker.com/install/): | ||
|
|
||
| Before using this game, you need to install R as well as various packages, listed in the file [`src/dependencies.R`](https://github.com/timflutre/PlantBreedGame/blob/master/src/dependencies.R). | ||
| Then it should work on Unix-like operating systems (GNU/Linux, Mac OS) as well as on Microsoft Windows. | ||
| - [Install Docker Desktop on Windows](https://docs.docker.com/desktop/install/windows-install/) | ||
| - [Install Docker Desktop on Mac](https://docs.docker.com/desktop/install/mac-install/) | ||
|
|
||
| ## Locally on your computer | ||
|
|
||
| 1. Retrieve the Shiny application, by [downloading](https://github.com/timflutre/PlantBreedGame/archive/master.zip) it as a ZIP archive (then unzip it and rename the directory). | ||
| The docker images of this application is available on Docker Hub at [juliendiot/plantbreedgame](https://hub.docker.com/r/juliendiot/plantbreedgame/tags). | ||
|
|
||
| Here is how to do it in a terminal for Unix-like operating systems: | ||
|
|
||
| ``` | ||
| wget https://github.com/timflutre/PlantBreedGame/archive/master.zip | ||
| unzip master.zip | ||
| mv PlantBreedGame-master PlantBreedGame | ||
| ``` | ||
|
|
||
| The package can also be installed after cloning the git repository: | ||
|
|
||
| ``` | ||
| git clone [email protected]:timflutre/PlantBreedGame.git | ||
| ``` | ||
|
|
||
| 2. Finally, open a R session, and execute the following commands: | ||
|
|
||
| ``` | ||
| library(shiny) | ||
| setwd("path/to/PlantBreedGame") | ||
| runApp() | ||
| ``` | ||
|
|
||
| A web page should automatically open in your default web browser, and you should be able to start playing. | ||
| See the explanations below in the section "Usage". | ||
|
|
||
| ## To set up your own server | ||
|
|
||
| _It is highly recommended to start by installing the application on your computer (see the previous section)._ | ||
|
|
||
| First, you need to have a [Shiny server](https://www.rstudio.com/products/shiny/shiny-server/) installed and running, say, in `/srv/shiny-server`. | ||
| We only tested with the open source version, but it should also work with the pro version. | ||
| For all this, have a look at the official [documentation](http://docs.rstudio.com/shiny-server/). | ||
|
|
||
| Second, you need to add an application to the server. | ||
| Start by downloading, for instance in your home, our Shiny application as a ZIP archive or clone the git repository (see explanations in the previous section): | ||
|
|
||
| ``` | ||
| cd ~ | ||
| wget https://github.com/timflutre/PlantBreedGame/archive/master.zip | ||
| unzip master.zip | ||
| mv PlantBreedGame-master PlantBreedGame | ||
| ``` | ||
|
|
||
| Then, create a new directory for the application (let's call it `breeding-game` here): | ||
|
|
||
| ``` | ||
| mkdir /srv/shiny-server/breeding-game | ||
| ``` | ||
|
|
||
| and copy inside the content of the Shiny application you just downloaded: | ||
|
|
||
| ``` | ||
| cp -r ~/PlantBreedGame-master/* /srv/shiny-server/breeding-game | ||
| ``` | ||
|
|
||
| By default, the Shiny server runs as a unix user named `shiny`. | ||
| You hence need to create a unix group, named for instance `breeding`, to which the `shiny` user can be added (the Shiny server may need to be restarted for this to be taken into account). | ||
|
|
||
| Everything inside the `breeding-game` directory should be readable and writable for users who are part of the `breeding` group. | ||
| This is particularly the case for the data set (`data` directory, generated by running `plantbreedgame_setup.Rmd`, see the previous section). | ||
| Those images are tagged in 3 different ways: | ||
| - `latest`: The latest stable version | ||
| - `development`: The latest development version | ||
| - `X.X.X`: The image corresponding to `plantBreedGame` version `X.X.X` | ||
|
|
||
| ``` | ||
| chgrp -R breeding /srv/shiny-server/breeding-game | ||
| chmod -R ug+rw,o-rwx /srv/shiny-server/breeding-game | ||
| ``` | ||
| In the following commands, you can replace `juliendiot/plantbreedgame:latest` | ||
| with the version you want to use eg. `juliendiot/plantbreedgame:1.1.0` or `juliendiot/plantbreedgame:development`. | ||
|
|
||
| Now go to the URL of the `breeding-game` application made available by your Shiny server. | ||
| If you encounter an error, look at the log, for instance: | ||
| Once docker is installed on your system you can start the game application with the command: | ||
|
|
||
| ```sh | ||
| docker run -d --rm --name plantbreedgame -p 80:3838 \ | ||
| -v /host/path/to/plantBreedGameData:/var/lib/plantBreedGame \ | ||
| juliendiot/plantbreedgame:latest | ||
| ``` | ||
| less /var/log/shiny-server/breeding-game-shiny-20180129-100752-39427.log | ||
| ``` | ||
|
|
||
| Errors may be due to missing packages, otherwise report an issue (see below). | ||
| Once all requested packages are installed, you should be able to start playing. | ||
| See the explanations below in the section "Usage". | ||
|
|
||
| ## :whale2: Docker | ||
| The options used in this command are detailed in [the official documentation of the `docker run` command](https://docs.docker.com/reference/cli/docker/container/run/). | ||
|
|
||
| Thank to docker, you can deploy this application without installing anything more than docker on your server. | ||
| There is a quick breakdown to present some option you can modify: | ||
|
|
||
| To install docker please refer here: [ubuntu](https://docs.docker.com/install/linux/docker-ce/ubuntu/), [debian](https://docs.docker.com/install/linux/docker-ce/debian/), [other](https://docs.docker.com/install/). | ||
| - `--name plantbreedgame` specify the name of the container. | ||
| - `-p 80:3838` control the port mapping between the docker container and the host. | ||
| Here: | ||
| - `80` is the port on the host (your machine). You can choose another available | ||
| port if you like. | ||
| - `3838` is the the application is listenning to inside the container. | ||
| You can not modify it. | ||
| - `-v /host/path/to/plantBreedGameData:/var/lib/plantBreedGame` control where | ||
| the application will save data to allow persistent storage across container runs. | ||
| - `/host/path/to/plantBreedGameData` is the path on the host where the game | ||
| data is stored you should **replace with the actual path you want to use**. | ||
| - `/var/lib/plantBreedGame` is the directory inside the container where the | ||
| game will store its data. **You cannot change this path**. | ||
|
|
||
| ### Deployment | ||
|
|
||
| A docker image of this application is available on Docker Hub: [juliendiot/plantbreedgame](https://hub.docker.com/r/juliendiot/plantbreedgame/tags). | ||
| Once you launched the game, the application will be available at: http://localhost:80 | ||
|
|
||
| Those images are tagged in 3 different ways: | ||
| - `latest`: The latest stable version | ||
| - `development`: The latest development version | ||
| - `X.X.X`: The image corresponding the plantBreedGame version `X.X.X` | ||
|
|
||
| In the following commands, you can replace `juliendiot/plantbreedgame:latest` | ||
| with the version you want to use. | ||
| > Note: **For testing purpose**, you can ommit the option | ||
| `-v /host/path/to/plantBreedGameData:/var/lib/plantBreedGame`. | ||
| However, game's data will not persist if you stop the container. | ||
|
|
||
| #### 1st method | ||
|
|
||
| For **testing purpose**, the simplest way to run the application using docker is with this command: | ||
| To stop the container you can use: | ||
|
|
||
| ```sh | ||
| docker run -d --rm --name plantbreedgame -p 80:3838 juliendiot/plantbreedgame:latest | ||
| docker stop plantbreedgame | ||
| ``` | ||
|
|
||
| The application is then accessible on the host machine on port `80` at the path `/PlantBreedGame`, for example: `localhost:80/PlantBreedGame` on your personal computer. | ||
| > Note: In case you use a different container name, you should replace | ||
| `plantbreedgame` with the name of the container specify with the `--name` option | ||
| you used to start the container. | ||
|
|
||
| Be careful ! **Stopping this container will erase all the progress of the players**. | ||
| ## Other installation method | ||
|
|
||
| #### 2nd method | ||
| For people on Mac or Linux (or Windows subsystem for linux), you can instal the game with [Nix](https://nixos.org/). | ||
|
|
||
| For actual game session, you need to specify to docker a persistent | ||
| ["volume"](https://docs.docker.com/engine/storage/volumes/#start-a-container-with-a-volume) | ||
| where it can save and keep the game data when the container is stoped. | ||
| To install nix you can visit: https://github.com/DeterminateSystems/nix-installer | ||
|
|
||
| With the command below: | ||
| Once Nix is installed you can lanch the game application with | ||
|
|
||
| ```sh | ||
| docker run -d --rm --name plantbreedgame -p 80:3838 \ | ||
| -v /host/path/to/plantBreedGameData:/var/lib/plantBreedGame \ | ||
| juliendiot/plantbreedgame:latest | ||
| mkdir plantBreedGame # create a new directory | ||
| cd plantBreedGame # move to this directory | ||
| nix build github:timflutre/PlantBreedGame # build the application | ||
| ./result/bin/plantBreedGame --host 127.0.0.1 --port 3838 # start the application | ||
| ``` | ||
|
|
||
| The game data will be saved in the host machine at `/host/path/to/plantBreedGameData`. | ||
| You can select any location you want. | ||
|
|
||
| The game data will be stored at `$HOME/.local/share/plantBreedGame`. | ||
|
|
||
| # Usage | ||
|
|
||
|
|
@@ -188,20 +129,19 @@ The `Theory` tab can be helpful. | |
|
|
||
| The `Evaluation` tab can be used to compare new genotypes (from different players) with the initial lines. | ||
|
|
||
| If you want to organize a real playing session, you need to create as many breeders as there are players or player teams. | ||
| For this, you need to log in as the "admin" breeder with the "game-master" status. | ||
| If you want to organize a real playing session, you need to create as many breeders as there are players or players teams. | ||
| For this, you need to log in as the "admin" breeder. | ||
| Initially, its password is set to `1234`, but this can (and should!) be changed via the tab `Admin`. | ||
| This tab also allows a game master to create new breeders and sessions, among other things. | ||
|
|
||
| You can modify some key parameters of the game, e.g., effective population size, heritabilities, genetic correlation. | ||
| For this, you need to edit the setup file [`plantbreedgame_setup.Rmd`](https://github.com/timflutre/PlantBreedGame/blob/master/plantbreedgame_setup.Rmd), notably by changing the parameters' values in the sections `Simulate haplotypes and genotypes` and `Simulate phenotypes` (e.g., subsection `Simulation procedure for trait 1`). | ||
|
|
||
| # Development environment | ||
|
|
||
| # Nix :snowflake: | ||
| ## Nix :snowflake: | ||
|
|
||
| This repository uses a "[nix](https://nixos.org/) flake" and [`direnv`](https://direnv.net/). If you have nix and direnv installed just `cd` in this repo, enable direnv (`direnv allow`) and all dependencies will be automatically installed and available in a dedicated environment. | ||
|
|
||
| You can then launch the application with: | ||
| After clonning this repository, and `cd` to it you can then launch the application with: | ||
|
|
||
| ```sh | ||
| nix run | ||
|
|
||