FIRST Server

A public, freely available server is located at The below information goes into how to stand up your own FIRST server. Keep in mind the current authorization mechanism is OAuth2 from Google. This can be expanded to include other OAuth2 services, however, it is important to keep in mind that OAuth2 authorization requires a developer/app/project specific data to enable. Furthermore, Google’s OAuth will only redirect to localhost or a domain name.



To quickly install FIRST, we use Docker. Install Docker before following the below instructions.

Installing your own FIRST server can be quick and easy with an Ubuntu machine and docker. The below instructions will use Docker to install FIRST, its dependencies, configure Apache, and create self signed certs. This is more of a production type build, if you wish to install FIRST in a developer environment then you might want to leverage Django’s development server (scroll down for instructions). To install, enter the below commands into a shell.


After cloning the Git repo

Save your google auth json information to install/google_secret.json

Optionally, you can add install/ssl/apache.crt and apache.key file if you have an SSL certificate you would prefer to use.

$ apt-get install docker
$ git clone
$ cd FIRST-server
$ docker-compose -p first up -d

When the FIRST server is installed, no engines are installed. FIRST comes with three Engines: ExactMatch, MnemonicHashing, and BasicMasking. Enable to engines you want active by using the utilities/ script.


Before engines can be installed, the developer must be registered with the system. Ensure the developer is registered before progressing.

Python script can be provided with command line arguments or used as a shell. To quickly install the three available engines run the below commands:

$ cd FIRST-server/server/utilities
$ python install first.engines.exact_match ExactMatchEngine <developer_email>
$ python install first.engines.mnemonic_hash MnemonicHashEngine <developer_email>
$ python install first.engines.basic_masking BasicMaskingEngine <developer_email>

Once an engine is installed you can start using your FIRST installation to add and/or query for annotations. Without engines FIRST will still be able to store annotations, but will never return any results for query operations.


Manually installing FIRST

FIRST can be installed manually without Docker, however, this will require a little more work. Look at docker’s install/requirements.txt and install all dependencies. Afterwards, install the engines you want active (see above for quick engine installation) and run:

$ cd FIRST-server/server
$ python runserver