FIRST Server¶
A public, freely available server is located at first-plugin.us. 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.
Installing¶
Note
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.
Important
After cloning the Git repo
Save your google auth json information to install/google_secret.json. To generate a google_secret.json file you will need to go to https://console.developers.google.com, create a project, select the project, select Credentials in the left set of links under APIs & services. Once selected, select the Create credentials drop down menu and click OAuth client ID. Select Web application, and fill out the details. Set the Authorized redirect URIs to your server name with /oauth/google
Examples
http://localhost:8888/oauth/google
http://first.talosintelligence.com/oauth/google
Once created you will have the option to down the JSON file containing the generated secret. 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 https://github.com/vrtadmin/FIRST-server.git
$ 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/engine_shell.py script.
Note
Before engines can be installed, the developer must be registered with the system. This can be accomplished through the web UI if OAuth has been setup or manually by the user_shell.py located in the utilities folder.
$ cd FIRST-server/server/utilities
$ python user_shell.py adduser <user_handle: johndoe#0001> <user email: john@doe.com>
Ensure the developer is registered before progressing.
Python script engine_shell.py 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 engine_shell.py install first_core.engines.exact_match ExactMatchEngine <developer_email>
$ python engine_shell.py install first_core.engines.mnemonic_hash MnemonicHashEngine <developer_email>
$ python engine_shell.py install first_core.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.
Attention
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 manage.py runserver 0.0.0.0:1337