Comment on page
Configure environment
The first step in customizing your project is to configure your environment.
The initial configuration of your exbuilder project involves creating a
.env file by making a copy of the .env-sample file. You do not have to do anything more, but if you'd like to do some customization, the following environment variables are available:You can (and probably should) customize your project's name. exbuilder uses this variable to name your project's containers. This is especially important and necessary for distinguishing multiple different exbuilder projects.
variable | default | description |
PROJECT_NAME | exbuilder | Used to name your project's containers. No spaces. |
You can also customize your directory structure. exbuilder's docker containers expect an
experiments directory, a database directory, and an analyses directory. It will generate these folders if they are missing from your project. If you change the names of these directories, you need to let exbuildr know their new names using the following environment variables. If you want to delete one of these folders, you can, but you also need to remove the containers that require them from your docker-compose.yml file.variable | default | description |
EXPERIMENTS_DIRECTORY | experiments | Name of experiments directory. No spaces. |
DATABASE_DIRECTORY | database | Name of database directory. No spaces. |
ANALYSES_DIRECTORY | analyses | Name of analyses directory. No spaces. |
You can configure your database using the following variables. We recommend leaving this as is for local development (or changing only
DB_PASSWORD to whatever you want your password to be). We do not recommend changing the rest of the variables unless you are completely customizing your database (like with a custom docker container).variable | default | description |
DB_HOST | postgres | Database host. We don't recommend changing this. |
DB_PORT | 5432 | Port the database will be exposed on. We don't recommend changing this. |
DB_NAME | exbuilder | Name of the database. We don't recommend changing this. |
DB_USER | exbuilder | Name of database user. We don't recommend changing this; doing so may cause breaking changes to exbuilder's default structure. |
DB_PASSWORD | password | Password to database. Change this to whatever you wish. |
DB_TABLE | experiments.runs | Name of runs table in database. We don't recommend changing this unless you are also changing the database structure. |
DB_SSLMODE | disable | SSL mode for database. We recommend setting this to disable for local development and to required when deployed on your server. |
If you are collecting audio recordings with exbuilder's AudioRecorder, you'll need an S3 bucket to push these sensitve data to. To do so, exbuilder will need to know the following details about your S3 bucket. If you aren't using an S3 bucket, you can leave these as they are.
variable | default | description |
S3_REGION | us-east-1 | Region of your S3 bucket. |
S3_ENDPOINT | Endpoint of your S3 bucket. | |
S3_KEY | YOURKEYHERE | Your S3 bucket key. |
S3_SECRET | YOURSECRET | Your S3 bucket secret. |
Both analysis containers require passwords to access. The default password for both containers is
password. You can leave these as is, or change them to whatever you want.variable | default | description |
JUPYTER_TOKEN | password | Password token for the jupyter container. Change this to whatever you like. |
RSTUDIO_PASSWORD | password | Password for the rstudio container. Change this to whatever you like. |
You can add any arbitrary environment variables to your
.env file if you want to.# name of your project; used to name your containers; no spaces
PROJECT_NAME = my-project-name
# my new variable
MY_VARIABLE = whatever-variable
To pass your variable to a docker container, use
${MY_VARIABLE} in your docker-compose.yml file. For example, if you need to pass a custom variable to the php container, you'd do so under the environment. php:
image: exbuilder/php:7.4-fmp-alpine
container_name: ${PROJECT_NAME}_php
volumes:
- ./${EXPERIMENTS_DIRECTORY}:/var/www/html:delegated
environment:
# add your custom variables here to pass to php container
- MY_VARIABLE = ${MY_VARIABLE}
Then, to retrieve them with a php script, you can do something like the following. Note that exbuilder does this in the
experiments/exbuilder/php/config.php<?php
// required to use the getenv library
require "vendor/autoload.php";
// retrieve the variable with getenv; I usually use an object
$my_vars = (object) [
'my_variable' => getenv('MY_VARIABLE')
];
// access the variable
$my_vars->my_variable
?>
Note that if your users (collegaues, public, etc) will need this variable, you should also add it to your project's
.env.sample file.To remove a container, simply delete that service from your
docker-compose.yml file. For example, most users do not require both a jupyter container and an rstudio container. Researchers normally prefer to analyze in one or the other. To remove the jupyter container, delete the following lines in the docker-compose.yml file. # delete this part of your docker-compose.yml file if
# you do not need the jupyter container
jupyter:
image: exbuilder/jupyter:r-4.0.3
environment:
- JUPYTER_TOKEN=${JUPYTER_TOKEN}
- JUPYTER_ENABLE_LAB=yes
volumes:
- ./${ANALYSES_DIRECTORY}:/home/jovyan/work
ports:
- 8989:8888
container_name: ${PROJECT_NAME}_jupyter
networks:
- exbuilder
Coming soon... example adding a python container