Unverified Commit ac90dd4f authored by Julie Sullivan's avatar Julie Sullivan Committed by GitHub
Browse files

Update README.md

parent 0dcd6b92
# docker-intermine-gradle
Docker for InterMine
You can use these docker images to create your own InterMine instance. You can launch our test InterMine (BioTestMine) or you can use your own data to build a custom mine.
## Requirements
- Docker
- Docker compose
- [Docker](https://docs.docker.com/install/)
- [Docker compose](https://docs.docker.com/compose/install/)
## Quickstart
### Option 1: Build images locally and start mine
Run the command to build the images locally and start an example InterMine instance - BioTestMine.
```bash
# Build images locally and start mine
docker-compose -f local.docker-compose.yml up --build --force-recreate
```
### Option 2: Pull images from Docker Hub and start mine
Alternatively, you can also use our images on docker hub.
```bash
# OR
# use the images on dockerhub
docker-compose -f dockerhub.docker-compose.yml up
```
Wait for 10-15 mins for the build to finish. Then visit **`localhost:9999/biotestmine`**
to visit your mine (yes it is that easy now!!)
> to surely determine whether build is finished or not, search for `intermine_builder exited with code 0` message in your docker-compose logs.
## Customizing your mine instance
Wait for 10-15 mins for the build to finish. Then visit **`localhost:9999/biotestmine`** to see your new mine.
### Using a custom mine
You can use your custom mine for the builds.
To determine whether build is finished or not, search for `intermine_builder exited with code 0` message in your docker-compose logs.
#### Step 1
- Set the git url of your mine to the env var `MINE_REPO_URL`. (directory structure similar to biotestmine is assumed)
If you do not have your mine hosted on github/gitlab then you can also mount your mine files directly to the build container. Add your mine folder inside `./data/mine` folder created by docker compose and uncomment the following line in the docker-compose.yml file.
```bash
# - ./data/mine/[PUT_YOUR_MINE_NAME_HERE]:/home/intermine/intermine/ [PUT_YOUR_MINE_NAME_HERE]
```
> Note: build will do a few changes to your mine files when mine files are directly mounted to the build container. So, it is recommended to use a copy of your mine for the build. This is not the case when you are using MINE_REPO_URL to pull mine files.
## Customizing your mine instance
#### Step 2
- Set `MINE_NAME` env var to your mine name.
Instead of building our test mine, you can launch your own custom InterMine by following these instructions.
> Make sure that the folder name matches with your mine name.
### Set Environment variables
#### Step 3
- Set `IM_DATA_DIR` env var to the data dir prefix that you have in your project.xml file. This will be used for search and replace to fix data locations inside the build container.
> Note: DO NOT add the trailing "/"
| ENV variable | Notes | Example |
| ------------- | ------------- | ------------- |
| MINE_REPO_URL | the git url of your mine | https://github.com/intermine/biotestmine |
| MINE_NAME | Name of your mine | FlyMine |
| IM_DATA_DIR | Data directory as used in your project XML file. | /data/flymine (no trailing slash "/") |
#### Step 4
- Follow [Adding data and project configs](#adding-data-and-project-configs) section to load data and config to your mine.
If you do not have your mine publically hosted then you can also mount your mine files directly to the build container. Add your mine folder inside `./data/mine` folder created by docker compose and uncomment the following line in the docker-compose.yml file. This is not recommended as the build will alter your source files.
```bash
# - ./data/mine/[PUT_YOUR_MINE_NAME_HERE]:/home/intermine/intermine/[PUT_YOUR_MINE_NAME_HERE]
### Adding data and project configs
```
#### Data
### Update data location
After quickstart you have a data folder created at your **current working directory**.
Create the directory `./data/mine/data` in your **current working directory**. If you did the quickstart above, it will already have been created for you.
You can also create the folder structure on your own if you do not want to do a quickstart. Create a folder structure like `./data/mine/data`
Uncomment the following line in intermine_builder section of your docker-compose file:
Add your data files to **`./data/mine/data`** folder and then uncomment the following line in intermine_builder section of your docker-compose file:
```bash
# - ./data/mine/data:/home/intermine/intermine/data
```
If you do not want to copy your data files over then change location of data files in your docker-compose file from **`./data/mine/data`** folder to your desired folder location in docker-compose.yml file.
> Remeber to create a folder for every data source you use. Also make sure that you have appropriate permissions for mounting your data dir to a docker container.
Update "./data/mine/data" to be the full path to your data directory.
#### Configs
### Configs
Add your config files to **`./data/mine/config`** folder. Configs include your properties file.
Add your mine property file (e.g. flymine.properties) to the **`./data/mine/config`** folder.
> In your properties file, do the following changes:
......@@ -91,29 +84,22 @@ Add your config files to **`./data/mine/config`** folder. Configs include your p
webapp.manager=TOMCAT_USER
webapp.password=TOMCAT_PWD
### Changing default settings
The build will replace these placeholders with the generated usernames and passwords.
### Change default settings (optional)
You can configure a lot of options by creating a `.env` file in the current working directory and adding the required key value pairs. These are used as env vars by docker-compose. For example:
```bash
MINE_NAME=humanmine
MINE_REPO_URL=https://github.com/julie-sullivan/humanmine
MINE_REPO_URL=https://github.com/intermine/humanmine
IM_DATA_DIR=/tmp/data
```
Available options are:
- MINE_NAME
Set your desired mine name here.
- MINE_REPO_URL
Add you mine github/gitlab url. It will be used to pull your mine inside build container
- IM_DATA_DIR
Set it to the data dir prefix that you have in your project.xml file. This will be used for search and replace to fix data locations inside the build container.
> Note: DO NOT add the trailing "/"
Here are the ENV variables available.
- TOMCAT_HOST_PORT
Set the port of your host machine to which tomcat docker container binds to. This is the port that you will use to access the mine webapp.
| ENV variable | Notes |
| ------------- | ------------- |
| MINE_REPO_URL | the git url of your mine |
| MINE_NAME | Name of your mine |
| IM_DATA_DIR | Data directory as used in your project XML file. This will be used for search and replace to fix data locations inside the build container.|
| TOMCAT_HOST_PORT | the port of your host machine to which tomcat docker container binds to |
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment