This is the main repository for the AmpliconRepository website. The documentation below provides intsructions on deploying the site locally, for development purposes.
Option A: Manually install modules and configure the environment step-by-step.
Option B: Use Docker to deploy the server and its environment on your system.
requirements.txt)
python -m venv ampliconenv
source ampliconenv/bin/activate
pip install -r requirements.txtOption B: Using conda's environment manager
conda create -n "ampliconenv" python>=3.8.0
conda activate ampliconenv
conda install pip -n ampliconenv
~/[anaconda3/miniconda3]/envs/ampliconenv/bin/pip install -r requirements.txt
Install MongoDB
sudo apt install mongodb-server-core
git config --global init.defaultBranch main
brew tap mongodb/brew
brew install mongodb-community@6.0
- If the package is not found you may need to follow the directions here.
mkdir -p ~/data/db/
ampliconenv environment active, run MongoDB locally:
mongod --dbpath ~/data/dbormongod --dbpath <DB_PATH>
URI:
mongodb://localhost:27017
/AmpliconRepository/projects/export DB_URI_SECRET='mongodb://localhost:27017' in your terminal to set the environment variable for your local database.
~/.bashrc filePeriodically, you will want to purge old or excessively large accumulated data from you DB. You can do this using the provided script
python purge-local-db.py
config.sh file from another developer (this contains secret key information)source config.shFor local deployments, you will need to ensure that the following two variables are set to FALSE, as shown below
export S3_STATIC_FILES=FALSE
export S3_FILE_DOWNLOADS='FALSE'IMPORTANT: After recieving your config.sh, please ensure you do not upload it to Github or make it available publicly anywhere.
Open a terminal window or tab with the ampliconenv environment active
Move to the caper/ folder (should see manage.py)
Run the server locally:
python manage.py runserver
Open the application on a web browser (recommend using a private/incognito window for faster development):
Troublshooting tip: If you face an error that says port 8000 is already in use, you can kill all tasks using that port by doing
sudo fuser -k 8000/tcp
These steps guide users on how to set up their development environment using Docker and docker compose as an alternative to python or conda-based package management and installation. This is the simplest way to locally deploy the server for new users.
Important: You first need to install docker>=20.10 on your machine.
To test the installation of Docker please do:
# check version: e.g. Docker version 20.10.8, build 3967b7d
docker --version
# check if compose module is present
docker compose --help
# check docker engine installation
sudo docker run hello-worldBuild and run your development webserver and mongo db using docker:
cd AmpliconRepository
# place config.sh in caper/, and place .env in current dir
# change UID and GID in .env to match the host configuration
# create all folders which you want to expose to the container
mkdir -p logs tmp .aws .git
docker compose -f docker-compose-dev.yml build --no-cache --progress=plain
docker compose -f docker-compose-dev.yml up -d
# then visit http://localhost:8000/ in your web browser
# once finished, to shutdown:
docker compose -f docker-compose-dev.yml down# for linux
sudo systemctl start docker
docker --help
docker compose --help
# or alternatively start manually from interface (macos or windows)git clone https://github.com/AmpliconSuite/AmpliconRepository.gitThis command will create a Docker image genepattern/amplicon-repo:dev-test with your environment, all dependencies and application code you need to run the webserver.
Additionally, this command will pull a mongo:4 image for the test database.
First, obtain the secret files .env and config.sh from another developer. Do not share these files with others outside the project. Do not upload them anywhere. Keep them private.
Next, Place .env under AmpliconRepository/ and config.sh under AmpliconRepository/caper/.
You should see these required files:
docker-compose-dev.ymlDockerfile.env requirements.txtcaper/config.shcd AmpliconRepository
docker compose -f docker-compose-dev.yml build --progress=plain --no-cacheThis command will:
amplicon-dev) and one for the mongo database (ampliconrepository_mongodb_1).env to configure all environment variables used by the webserver and mongodb localhost:800027017-v ${PWD}:/srv/:rw# create all folders exposed to container
mkdir -p logs tmp .aws .git
# start container using the host UID and GID (change in .env)
docker compose -f docker-compose-dev.yml up -d
#[+] Running 2/2
# ⠿ Container ampliconrepository-mongodb-1 Started 0.3s
# ⠿ Container amplicon-dev Started 1.1sTo check if your containers are running do:
docker psand you should see something like below:
# CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
# 311a560ec20a genepattern/amplicon-repo:dev "/bin/sh -c 'echo \"H…" 3 minutes ago Up About a minute 0.0.0.0:8000->8000/tcp amplicon-dev
# deaa521621f1 mongo:4 "docker-entrypoint.s…" 4 days ago Up About a minute 0.0.0.0:27017->27017/tcp ampliconrepository_mongodb_1To view the site locally, visit http://localhost:8000/ in your web browser.
To stop the webserver and mongodb service:
docker compose -f docker-compose-dev.yml down
#[+] Running 3/2
# ⠿ Container amplicon-dev Removed 10.3s
# ⠿ Container ampliconrepository-mongodb-1 Removed 0.3s
# ⠿ Network ampliconrepository_default Removed 0.0sBefore you build your image you can check if the config.sh is set correctly by doing:
docker compose -f docker-compose-dev.yml configThis command will show you the docker-compose-dev.yml customized with your environment variables.
You can check the environment variables which your running container uses:
docker inspect -f \
'{{range $index, $value := .Config.Env}} {{$value}}{{println}}{{end}}' \
container_iddocker ps and check if the port mapping is correct, i.e. you should see 0.0.0.0:8000->8000=host_localip:host_port->docker_portdocker run -p 8000:8000 ...=HOST:DOCKER8000 to be able to use the Google Authentication in the AppAMPLICON_ENV_PORT if you want to use another port on the host machine, then rebuild the docker image.permission denied/read only database please set the read-write permissions on your local machine to 777 for the following
sudo chmod 777 logs/ tmp/ .aws/ caper/caper.sqlite3 -Rdocker compose may not be available and you will need to install docker-compose and use that, replacing docker compose with docker-compose.unix /var/run/docker.sock: connect: permission denied -> seeUID and GID in your .env file to match the host UID GID, or run as so:
env UID=${UID} GID=${GID} docker compose -f docker-compose-dev.yml upcd AmpliconRepository; mkdir -p logs tmp .aws .gitmongodb instance is not running or you get ampliconrepository-mongodb-1 exited with code 14? Try do cd AmpliconRepository; rm -rf data and restart using docker-composeThese datasets are ready to upload to the site for testing purposes.
caper.sqlite3 along with your other changes. caper.sqlite3 is not among the changed files in a PR.The server is currently running on an EC2 instance through Docker. The ports active on HTTP and HTTPS through AWS Load Balancer. There are two main scripts to start and stop the server.
Note: While we provide a Dockerfile, local deployment of the site using the docker will only properly work on AWS. Local deployment should be done with a local install using the steps above.
ampliconrepo-ubuntu-20.04)
cd /home/ubuntu/caper/
docker ps(look for a container called amplicon)
./start-server.sh
ampliconrepo-ubuntu-20.04)
cd /home/ubuntu/caper/
docker ps(look for a container called amplicon)
./stop-server.sh
ampliconrepo-ubuntu-20.04 in us-east-1)
cd /home/ubuntu/AmpliconRepository-prod/source caper/config.sh
git fetchgit pullgit checkout tags/<release tag in github>
./stop-server.sh./start-server.sh