Run a server
A refgenie server shares your assets with other people. Clients subscribe to it and refgenie pull from it, the same way they pull from the public server at https://api.refgenie.org. Run your own to share private or custom assets inside your group, or to publish assets for the community.
This page walks through the steps. For flags, endpoints and environment variables, see the server reference.
1. Install
Section titled “1. Install”pip install "refgenie[server]>=1.0.0a3"2. Build and stage assets
Section titled “2. Build and stage assets”The server serves only staged assets. Staging puts a servable copy of each asset (a symlink, a .tgz archive, or both, depending on the asset class) in the stage folder, ~/.refgenie/archives by default.
refgenie build hg38/fasta --stagerefgenie stage add hg38/bowtie2_index mm10/fastarefgenie stage listSee Build assets and Stage assets for serving.
3. Start the server
Section titled “3. Start the server”refgenie serveThe server listens on all network interfaces, port 8000. Open http://localhost:8000/docs for the interactive API docs. The server has no web UI of its own; to browse a catalog in a browser, run refgenie dash. Use --port to pick another port.
4. Pull from it
Section titled “4. Pull from it”On a client machine, subscribe to your server and pull:
refgenie subscribe -s http://your-server:8000refgenie pull hg38/fastaRun it in production
Section titled “Run it in production”For a server other people rely on:
- Use PostgreSQL instead of the default SQLite database. See Database backends.
- Put it behind a reverse proxy such as nginx with HTTPS. Do not use
--reloadin production. - Host files on cloud storage. Push staged assets to an S3 bucket or web server with
refgenie push. When an asset has been pushed to anhttporhttpsremote, the server sends download requests there instead of serving the file itself. See Configure remote storage and Remotes on a server. - Serve data channels. The server re-serves the data channels listed in its config file, so clients can get recipes and asset classes from it. See Serve data channels.
Docker
Section titled “Docker”The refgenie repository includes a Dockerfile that builds a server image:
git clone https://github.com/refgenie/refgenie.gitcd refgeniedocker build -t refgenie-server .The image reads its database settings from deployment/config.yaml, a PostgreSQL config filled in from environment variables. It listens on port 80:
docker run --rm -d -p 8000:80 \ -e POSTGRES_HOST=db.example.org \ -e POSTGRES_DB=refgenie \ -e POSTGRES_USER=refgenie_user \ -e POSTGRES_PASSWORD=your_secure_password \ --name refgenie-server \ refgenie-serverPoint it at the database you built and staged into, or have it import a published catalog with REFGENIE_CATALOG_URL (see the server reference).
Troubleshooting
Section titled “Troubleshooting”- The server will not start. Install the extras with
pip install "refgenie[server]>=1.0.0a3", check that the port is free, and check your database config. - Assets do not show up. Check that they are staged (
refgenie stage list) and that the server uses the same database and stage folder you staged into. - Downloads fail. Check that the staged files exist in the stage folder, or that the asset was pushed to the remote. The server log names the missing path.
See also
Section titled “See also”- Server reference
- Use the dashboard, the local web UI for your own refgenie
- Public servers