TAKAHASHI GROUP (情報化学研究室)

Hokkaido University

WEB APPLICATION FOR SEARCHING CHEMICAL ACTIONS AND NETWORKS

SCAN
Server Setup Manual
ENGLISH ORIGINALSCAN Server Setup Manual

HOKKAIDO UNIVERSITY - TAKAHASHI GROUP - INFORMATION CHEMISTRY LABORATORYSCAN Server Setup Manual
CONTRIBUTORSSCAN System Developers

Micke Nicander Kuwahara
Jun Fujima
This document was last updated
April 17, 2023 14:00
SCAN Web Application[Searching Chemical Actions and Networks]
Copyright © 2018 Keisuke Takahashi, Micke Nicander Kuwahara
in Takahashi Group (情報化学研究室) of Hokkaido University********************************************************************
SCAN is licensed under the GNU GPL License, Version 3.0;
you may not use this file except in compliance with the License.
You may obtain a copy of the License athttps://www.gnu.org/licenses/gpl-3.0.en.html
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions andlimitations under the License.
For any further information, visit the project GitHub athttps://github.com/scan-team/scan-platform-test********************************************************************
Takahashi Group
Hokkaido University, Faculty of Science, Department of Chemistry,
7th building, Room 7-510, Kita 10, Nishi 8, Kita-ku,
Sapporo, 060-0810, Japan.
scan-team@sci.hokudai.ac.jp

1

SCAN Server Setup Manual

Table of Contents
CONTRIBUTORS.................................................................................................................1
Table of Contents..................................................................................................................................2
Preface..................................................................................................................................................3
Introduction..........................................................................................................................................4
SCAN Architecture..........................................................................................................................4
Web-based Browsing Interface........................................................................................................5
Server Setup Manual............................................................................................................................6
Prerequisites.....................................................................................................................................6
Preparing the Environment..............................................................................................................7
Setting up and configuring an Auth0 account....................................................................7
Scan Server Configuration.............................................................................................................10
Getting SCAN from Github.............................................................................................11
Creating and editing SCAN project configuration files...................................................11
Scan Server Build and Startup.......................................................................................................13
Data Registration Procedure..........................................................................................................15
Registration of sample data.............................................................................................15
Summary........................................................................................................................................15
Index...................................................................................................................................................16
Figure Index........................................................................................................................................16
Table Index.........................................................................................................................................162

SCAN Server Setup Manual

Preface
A few words from the creators.

This manual is attempting to be a extensive guide to anyone who wishes to setup their own
public SCAN Server found online at GitHub at https://github.com/scan-team/scan-platformtest . The interactive chemical reaction platform, SCAN, is developed for analyzing chemical
reaction networks. SCAN offers the chemical reaction path network database, visualization,and network analysis tools. In particular, SCAN is a web-based platform that allows users to perform
interactive chemical reaction path network visualization and data science techniques with simple
operation. SCAN is designed to provide a user-friendly graphic user interface, making preexistingknowledge of programming and skill sets optional. Thus, SCAN is proposed to be an alternative tool for
analyzing and understanding chemical reaction networks.
SCAN is basically a visualization and analyzing tool for network data, with exclusive focus on chemical
reaction data. SCAN was originally mainly developed to use AFIR data, but that is not a limitation
chisseled in stone. Any developer who downloads the SCAN code and and server setup manual are free
to alter the database as one see fit and use any data they like.
So to be clear, the SCAN software development team is not involved in chosing and uploading the data,
and we do not take any responisbility for the data content. Our only focus is the toolsets and the things
one can do with the data chosen.
For any AFIR data related issues, please contact the iCReDD (https://www.icredd.hokudai.ac.jp) team at
Hokkaido University (lead by Professor Satoshi Maeda).

April 17, 2023
SCAN Software Project Leader
Director of Takahashi Group - Information Chemistry Laboratory

Professor Keisuke Takahashi
SCAN Software System Lead Developer

Micke Nicander Kuwahara

3

SCAN Server Setup Manual

Chapter

1

Introduction

Get to know what SCAN is and what it can do for you as a researcher and chemist.

Understanding the chemical reaction answers the fundamental mystery of how products areformed from reactants. First principle calculations unveil that the chemical reaction is acomplex matter as it involves a tremendous number of intermediates. In other words, achemical reaction can be treated as a form of a complex network consisting of numerous
molecular interactions. While it is difficult to capture the details of molecular interactions in anexperiment, first principle calculations play a major role in understanding such a complex reaction
map. In particular, numerous automatic chemical reaction searching tools have been developed such as
freezing string method with the Berny algorithm, single/double-ended growing string methods,
artificial force induced reaction (AFIR), reaction mechanism generator (RMG), and kinbot. Althoughsuch complex reaction networks become available, the question arises over how such complex networks
can be understood and how knowledge can be extracted, rendering tools for extracting the knowledge
from networks necessary.
Extracting knowledge from the chemical reaction network involves multiple steps and processes. In
particular, organization of chemical reaction database, statistical analysis, network visualization, andgraph theory are involved. Several network visualization tools are available such as Cytoscape andGephi which offer network visualization and graph theory analysis. Moreover, it has been demonstrated
that graph theory such as centrality analysis is found to be effective when determining intermediates.
However, these processes are strongly linked to each other, meaning that the individual development ofeach process could limit the ability to extract knowledge. In addition, network data visualization andanalysis often require particular skillsets as well as advanced programming skills, which can act asbarriers towards performing such analyses. Therefore, it is crucial to establish a centralized, interactive,
and user-friendly platform which has the ability to utilize these processes simultaneously. Here,
Searching Chemical Action and Network (SCAN) is introduced where a platform for interactive chemical
reaction network is designed and proposed where chemical reaction network producded by the AFIR
method. The SCAN platform is available at https://scan.sci.hokudai.ac.jp/ where it offers the users to
explore, visualize and analyze the chemical reaction network data generated by the first principle
calculation. Thus, SCAN offers the search and understand the complex chemical reaction network.

SCAN Architecture
The concept of SCAN is to store and share the chemical reaction network generated by the firstprinciple calculation where interactive network visualization and network analysis are also provided. Inorder to achieve the flexible reuse of data, the layered architecture consists of a data lake, data
warehouse, and data mart. Here, chemical reaction network generated by AFIR methods is used as aprototype chemical reaction network data where data is previously published. The chemical reaction
network data generated by AFIR contains numerous log files which are classified as raw data. These raw
4

SCAN Server Setup Manual

data are stored in their original form with no modifications. This data storage unit is defined as adata lake. The raw data provided by the data lake is then preprocessed for network visualization andnetwork analysis and stored in a data warehouse. Lastly, the data warehouse is accessed by the data
mart, which provides application services such as data visualization, data analysis, and an
application programming interface for data sharing.

Web-based Browsing Interface
Web applications are constructed where the three-layered architecture are used as the foundation. The
web application directly connects to the data mart, which allows the user to directly access the webgraphic user interface to carry out network visualization, network analysis, and data downloading
without previous experience with programming or data preprocessing. This is particularly attractive as
it expands access to chemical reaction analysis to researchers that may not have the knowledge orskillsets required for such research.

5

SCAN Server Setup Manual

Chapter

Server Setup Manual

2

So you have visitied SCAN online and you have a feeling that it may be what you are looking for,but you want to have your own server. Well, then you are at the right place, because here we will
help you download and install your own SCAN server.

In this chapter we will try to explain everything that you need to know about installing and setingup your own SCAN server environment for both local and public use. There are quite a lot of things
to do and it can be quite a daunting task. But hopefully with this manual you are going to be allfine. So let's get to it.

Prerequisites
Before you even start looking looking in the direction of SCAN you first need to make sure your system
is ready for this. The following preparations are required prior to the implementation of any SCAN
Server as further explained in this document.
1. A computer with Ubuntu or Linux OS, with the following systems installed and running:a) Docker and Docker-Compose•

It's not within the scope of this document to explain anything about Docker, so that willbe all on you, but here is a link to start if you do not already have Docker.
•

https://www.docker.comb) Python3•

It's not within the scope of this document to explain anything about Python either, but
we guess you know where to go and find out what you need about it online.

2. [Only for public server, not needed for local version]:a) Obtain a domain name for your SCAN app and register it in the DNSb) Obtain proper SSL certificatec) Register for a Google Analytics ID (optional and how to is not within the scope of this document)

6

SCAN Server Setup Manual

Preparing the Environment
After you have made sure that your computer has the required foundation, it is time to install andconfigure all of the necessities and parts that SCAN needs to run.

Setting up and configuring an Auth0 accountIn this section we will explain how you create an account for the auth0 authentication server which isneeded to create and manage user accounts for the SCAN web platform.
1) Go to https://auth0.com in your browser.

Figure 1: The front page of the Auth0 website that will be your user accounts manager
2) Click on the “Sign Up” button to go to the user registration page in the top right section as seenin Figure 1.
3) Enter your e-mail address and then click Continue to go to the account creation screen. Enter
your password and click Continue. This can be seen below in Figure 2.

Figure 2: To create a basic User Manager account with Auth0 is free7

SCAN Server Setup Manual
4) Select "Account Type", "Company Name" and "Company Size" and click "Next".
Confirm "Tenant Domain" and "Region" and click "Create Account" to create the account asseen in Figure 3.

Figure 3: The domain name is needed to be obtained before you get here in the process.
5) After you have signed up, the dashboard page will be displayed as can be seen in Figure 4.

Figure 4: In the Auth0 Dashboard you can now configure the login system for your
SCAN server.
6) Click “Applications” at the top left of that screen, followed by a click on “Applications” directly
below. After that, in the new view in the main area, click "Default App" in order to to move tothe setting screen. What was just described can be seen in Figure 5 below.

8

SCAN Server Setup Manual

Figure 5: Click yourself to the Default App configuration view.
7) Under the Settings tab you will find the parts you need to fill in by scrolling down as shown in
Figure 6.

Figure 6: Scroll down in this view to get to the parts that need to changed or
added.
8) Enter the URL of the SCAN server in the “Application Login URI” field, found by scrolling further
down on the settings page. In Figure 7 you can see the field in question.

Figure 7: Make sure you have properly registered the url before this step.
9

SCAN Server Setup Manual
9) Next scroll down to "Allowed Callback URLs" and in that field enter "the Server
URL/api/auth/callback" as indicated in Figure 8.

Figure 8: Type in the same url as before, but with the additional path.
10) Below the above section can be found the "Allowed Logout URLs”. In that field just add theserver URL as noted in Figure 9.

Figure 9: Just fill in the same URL as before with no additional paths.
11) When you're done, scroll down and click 'Save Changes' at the bottom of the screen as seen in
Figure 10.

Figure 10: Save the settings and then you are ready to go.

Scan Server Configuration
In this section we are downloading the SCAN code to your server and help you setting it up andconfiguring it the way it need to be configured in order to run. We will assume that you are familiar
with the OS (Linux or Ubuntu) that your are working with, as well as GitHub in general, since none ofthose parts will be explained further in any details within the scope of this documentation. If you do notmaster any of those at any good-enough level, then we suggest you go online and find a tutorial andlearn.

10

SCAN Server Setup Manual

Getting SCAN from Github
1) Log in to the Linux server you are installing to, as the admin user and go to the location in thefile system where your SCAN server will reside.
2) Make a quick visit to the GitHub page for SCAN at https://github.com/scan-team/scanplatform-test, this is the project we will clone and work with. Also take a quick glance at the
ReadMe to make sure all looks on par with this documentation. (The ReadMe is updated first ifchanges occur so if something different is stated there, that is what goes)3) Clone the SCAN repository from GitHub to your server.
$ git clone https://github.com/scan-team/scan-platform-test.git my-scan$ git submodule update --init --recursive4) After the SCAN project has finished downloading from GitHub to your server, navigate to theroot of the project if you are not already there.

Creating and editing SCAN project configuration files
5) Create a copy of the .env.sample file, found at the root, and name the copy .env
$ cd my-scan/$ cp .env.sample .env

6) Open the .env file for editing (using your preferred code/text editor) and make the changes
required as seen in Figure 11, and as listed with description and example in the Table 1 below.
Item Name
API_ALLOWED_HOSTS
AUTH0_SECRETAUTH0_BASE_URL
AUTH0_ISSUER_BASE_URL
AUTH0_CLIENT_ID
AUTH0_CLIENT_SECRET
NEXT_PUBLIC_SCAN_API_PROXY_ROOTFASTAPI_SIMPLE_SECURITY_SECRE
T
NEXT_PUBLIC_GOOGLE_ANALYTICS_ID

Description
API accessible URL
Specify the URL of the server
Please specify a randomcharacter string.
Server URL
Look at AUTH0 application
settings: Domains
Look at AUTH0 application
settings: ClientID
Look at AUTH0 application
settings: ClientSecret
Add api / proxy to server URL
API access key (formanagement)
Please specify a random
stringSpecify the measurement ID
for data collection with
Google Analytics.

Examplehttps://yourhostname:8001/
Oi2Aich1theace6jaiyoekae3a
ethuizuoz
https://yourhostname/https://xxxx.auth0.com(xxxx is found in Auth0 Domain)

https://yourhostname/api/
proxycaaph5eicahneewuiKei3peeV
e8shi3I
G-X3ZZ5HVYYZTable 1: These are the environment variables that need to set properly.

11

SCAN Server Setup Manual

Figure 11: Configuring the .env file in the project root folder correctly is an important part.
7) Create a copy of nginx.conf.example from the scan-reverse-proxy/conf.d/directory and name it
nginx.conf$ cp nginx.conf.example nginx.conf

8) Open the nginx.conf file for editing (using your preferred code/text editor) and make thechanges required as seen in Figure 12, and as listed with description and example in the Table 2
below.
Item Name
ssl_certificate

SSL certificate file name1

Description/etc/ssl/certs/cert.pem

Examplessl_certificate_key

SSL private key file name/etc/ssl/certs/server.pem

Table 2: The SSL certificate keys needs to be registered

Figure 12: Change the names to point at the SSL key location of your computer

1No need to change the path part /etc/ssl/certs (those will be pointed correctly at in docker-compose.yml below)

12

SCAN Server Setup Manual
9) Create a copy of docker-compose.yml.example from the SCAN root folder and name it dockercompose.yml$ cp docker-compose.yml.example docker-compose.yml

10) Open the docker-compose.yml file for editing (using your preferred code/text editor) and makethe changes required as seen in Figure 13, and as listed with description and example in the
Table 3 below.
Item Name
nginx: volumes: -Description
Repoint the path of your local ssl
to the virtual path used by nginx.

ExampleYourSSLPath: /etc/ssl/certs

Table 3: Make sure you find the correct local location of the SSL certs

Figure 13: Your local location of the SSL certs

Scan Server Build and Startup
Now we have come to the project building and starting part of the documentation where we will
execute the Docker build process and see the SCAN server run for the first time.
1) Make sure that you are at the project root folder and then execute the build script.
$ ./build.sh2) Now the docker build process will start, and that may take some time, many minutes perhaps.
During that process, information on the process will be written into the terminal in various
colors, including red, but all should be well. At the end when all is finished there should be amessage that things have been successful.
3) If something fails, make sure to double check that you have done all previous parts up to this point
correctly. Read the error message and compare with the GitHub ReadMe file that all seem okay. Google theerror message if this documentation is not sufficient. After correcting any possible mistake, run the build
command above one more time.

13

SCAN Server Setup Manual4) After the Docker build process has finished successfully it is time to start the SCAN server via
the start script.
$ ./start.sh5) This process too will take time and a lot of messages will be printed to the terminal, but if allgoes well, as it should, at the end all docker containers started and running will be displayedwith a green 'Done' as seen in the Figure 14 below.

Figure 14: This is the view you want, showing that thesystem is all up and running as it should.
6) Now go to your browser and open up the website. If it is running with localhost then use that,
otherwise use the ip or URL that you have assigned during the configuration. (If you areaccessing your server remotely or for some reason can not use localhost, you must make sure to
update all links in .env and Auth0.com accordingly with your requested IP settings)
7) If all works as intended then you should see the website start page in your browser as seen in
Figure 15 below, with the difference that there are zero maps available, that we need to add in
the next step.

Figure 15: The SCAN website start page8) The 'Terms of Use' link and the 'Contact Us' link will most likely contain wrong information for your setup,
so please locate those files and edit them to your liking before deploying online.
9) If you later want to stop the server just execute the stop script, and wait for the server to finish.
$ ./stop.sh

14

SCAN Server Setup Manual

Data Registration Procedure
This section describes the procedure for registering sample data. If you are planning to run your own
data or GRRM (AFIR) data or in any other way alter the DB, then perhaps do that later after you madesure that the sample data work fine.

Registration of sample data
You can load the demo sample data into the database. The following two reaction pathway networks forurea synthesis are registered.
••Wöhler ’s urea
Synthesis

1) Download the sample data from the following URL, name it “export.sql”, and upload it to the
SCAN server.
https://drive.google.com/file/d/1VjsEwVdje4G1Ob1fEesMRXmRQRBaajr1/view?usp=sharing[if the link is not working, go to SCAN GitHub and locate a proper link there]
2) Register the sample data to the database. (make sure the paths and location of the export.sql iscorrect according to your computer.)$ scan-mariadb/import.sh ../export.sql

3) This might take a little while but when all is done the terminal should display that 100% datatransfer has been reached and all was completed successfully.
4) Now restart the website and it should surely look like Figure 15 above, with two maps available.

Summary
We wish that this Server Setup Manual have told you anything and everything you need to know about
how to setup and maintain a SCAN Web app server.
Congratulations on your newly gained knowledge and may it serve you well in your future endeavors.
Enjoy!

15

SCAN Server Setup Manual

Index
AFIR..................................................................4
Auth0.....................................................7, 11, 14
Build......................................................1, 13, 14
Chemical reaction......................................3, 4, 5
Data................................................3, 4, 5, 11, 15
Docker...................................................6, 13, 14

Github....................................1, 3, 10, 11, 13, 15
Networks.......................................................3, 4
Reaction map.....................................................4
SSL........................................................6, 12, 13.env............................................................11, 14

Figure Index
Figure 1: The front page of the Auth0 website that will be your user accounts manager....................7
Figure 2: To create a basic User Manager account with Auth0 is free.................................................7
Figure 3: The domain name is needed to be obtained before you get here in the process...................8
Figure 4: In the Auth0 Dashboard you can now configure the login system for your SCAN server.. .8
Figure 5: Click yourself to the Default App configuration view..........................................................9
Figure 6: Scroll down in this view to get to the parts that need to changed or added..........................9
Figure 7: Make sure you have properly registered the url before this step..........................................9
Figure 8: Type in the same url as before, but with the additional path...............................................10
Figure 9: Just fill in the same URL as before with no additional paths..............................................10
Figure 10: Save the settings and then you are ready to go.................................................................10
Figure 11: Configuring the .env file in the project root folder correctly is an important part...........12
Figure 12: Change the names to point at the SSL key location of your computer.............................12
Figure 13: Your local location of the SSL certs..................................................................................13
Figure 14: This is the view you want, showing that the system is all up and running as it should....14
Figure 15: The SCAN website start page...........................................................................................14

Table Index
Table 1: These are the environment variables that need to set properly.............................................11
Table 2: The SSL certificate keys needs to be registered...................................................................12
Table 3: Make sure you find the correct local location of the SSL certs............................................13

16

Thanks for your support