|
| 1 | +# Installation Guide |
| 2 | + |
| 3 | +## Prerequisites |
| 4 | +On the platform of your choice (we recommend Linux) please ensure you have the following installed: |
| 5 | +* Postgresql |
| 6 | + * Ensure you have a user you can use that has the ability to apply database migrations to the Ego database and to create extensions. |
| 7 | +* Java Runtime Environment version 11. |
| 8 | +* A configured OAuth2 OIDC provider with a clientId and clientSecret. (For example Google). |
| 9 | +* The UI ready to be hosted or already hosted somewhere. |
| 10 | + |
| 11 | +## Installation |
| 12 | + |
| 13 | +### Download Ego |
| 14 | + |
| 15 | +You can download the latest version of Ego from [here](https://artifacts.oicr.on.ca/artifactory/dcc-release/bio/overture/ego/[RELEASE]/ego-[RELEASE]-dist.tar.gz). |
| 16 | + |
| 17 | +Example using curl: |
| 18 | +```shell |
| 19 | +curl https://artifacts.oicr.on.ca/artifactory/dcc-release/bio/overture/ego/[RELEASE]/ego-[RELEASE]-dist.tar.gz -o ego-dist.tar.gz |
| 20 | +``` |
| 21 | + |
| 22 | +### Extract |
| 23 | +Once downloaded, extract the distribution. |
| 24 | + |
| 25 | +```shell |
| 26 | +tar zxvf ego-dist.tar.gz |
| 27 | +``` |
| 28 | + |
| 29 | +This should create a folder with the name of `ego-<version>` where `<version>` is the version number of the release. We recommend moving Ego out of you home directory, to a directory like `/srv`. You may need to use elevated privileges to do this. |
| 30 | + |
| 31 | +```shell |
| 32 | +$ sudo mv ego-4.1.0 /srv/ |
| 33 | +$ ls -l /srv/ |
| 34 | +total 4 |
| 35 | +drwxrwxr-x 8 ubuntu ubuntu 4096 Mar 11 18:51 ego-4.1.0 |
| 36 | +``` |
| 37 | + |
| 38 | +We also recommend creating a symlink with the name of ego-current should you ever want to update or rollback to previous version of Ego while maintaining one place to look at for running and configuring. |
| 39 | + |
| 40 | +```shell |
| 41 | +/srv$ sudo ln -sf ego-4.1.0 ego-current |
| 42 | +/srv$ ls -la |
| 43 | +total 12 |
| 44 | +drwxr-xr-x 3 root root 4096 Mar 11 18:56 . |
| 45 | +drwxr-xr-x 19 root root 4096 Mar 11 18:14 .. |
| 46 | +drwxrwxr-x 8 ubuntu ubuntu 4096 Mar 11 18:51 ego-4.1.0 |
| 47 | +lrwxrwxrwx 1 root root 9 Mar 11 18:56 ego-current -> ego-4.1.0 |
| 48 | +``` |
| 49 | + |
| 50 | +### Database Configuration |
| 51 | + |
| 52 | +The directory structure inside of the Ego directory is self-explanatory: |
| 53 | + |
| 54 | +```shell |
| 55 | +/srv/ego-current$ ls -l |
| 56 | +total 24 |
| 57 | +drwxrwxr-x 2 ubuntu ubuntu 4096 Mar 11 18:51 bin |
| 58 | +drwxrwxr-x 2 ubuntu ubuntu 4096 Mar 11 18:51 cert |
| 59 | +drwxr-xr-x 2 ubuntu ubuntu 4096 Mar 11 17:03 conf |
| 60 | +drwxrwxr-x 2 ubuntu ubuntu 4096 Mar 11 18:51 exec |
| 61 | +drwxr-xr-x 2 ubuntu ubuntu 4096 Mar 11 17:03 lib |
| 62 | +drwxr-xr-x 2 ubuntu ubuntu 4096 Mar 11 17:03 logs |
| 63 | +``` |
| 64 | + |
| 65 | +We want to navigate into the `conf` directory to edit the `application.yml` file. |
| 66 | + |
| 67 | +```shell |
| 68 | +vim conf/application.yml |
| 69 | +``` |
| 70 | + |
| 71 | +First thing we want to edit is the `spring.datasource` section replacing `<ego_db>`, `<db_user>`, and `<db_pass>` with the values you have configured in your postgresql instance: |
| 72 | +```yml |
| 73 | +# Datasource |
| 74 | +spring.datasource: |
| 75 | + driver-class-name: org.postgresql.Driver |
| 76 | + url: jdbc:postgresql://localhost:5432/<ego_db>?stringtype=unspecified |
| 77 | + |
| 78 | + username: <db_user> |
| 79 | + password: <db_pass> |
| 80 | + max-active: 10 |
| 81 | + max-idle: 1 |
| 82 | + min-idle: 1 |
| 83 | +``` |
| 84 | +
|
| 85 | +Next, as we have not applied any database migrations, we will want to enable flyway to automatically apply outstanding migrations on startup. Look for the `spring.flyway.enabled` setting and set it to `true`. Also, we will need to tell flyway where to find the migrations. As we are using the built in migrations, we can add: `locations: classpath:flyway/sql,classpath:db.migration`. |
| 86 | + |
| 87 | +```yml |
| 88 | +spring: |
| 89 | + flyway: |
| 90 | + enabled: true # SET THIS TO TRUE, DEFAULT IS FALSE |
| 91 | + user: <privileged_user> |
| 92 | + password: <privileged_user_password> |
| 93 | + locations: classpath:flyway/sql,classpath:db.migration |
| 94 | +``` |
| 95 | + |
| 96 | +As the migration requires elevated privileges to create extensions within postgresql, feel free to use a separate user for running them. |
| 97 | + |
| 98 | +### First Startup |
| 99 | +Now we are ready to start Ego and initialize the database. We will use the service wrapper `bin/ego` to start/stop/restart Ego. |
| 100 | + |
| 101 | +```shell |
| 102 | +/srv/ego-current$ bin/ego |
| 103 | +Usage: bin/ego [ console | start | stop | restart | condrestart | status | install | remove | dump ] |
| 104 | +
|
| 105 | +Commands: |
| 106 | + console Launch in the current console. |
| 107 | + start Start in the background as a daemon process. |
| 108 | + stop Stop if running as a daemon or in another console. |
| 109 | + restart Stop if running and then start. |
| 110 | + condrestart Restart only if already running. |
| 111 | + status Query the current status. |
| 112 | + install Install to start automatically when system boots. |
| 113 | + remove Uninstall. |
| 114 | + dump Request a Java thread dump if running. |
| 115 | +
|
| 116 | +``` |
| 117 | +Starting it up for the first time: |
| 118 | +```shell |
| 119 | +/srv/ego-current$ bin/ego start |
| 120 | +Starting EGO Server... |
| 121 | +Waiting for EGO Server...... |
| 122 | +running: PID:11994 |
| 123 | +``` |
| 124 | + |
| 125 | +If we look at the logs we should seem something like the following: |
| 126 | +```shell |
| 127 | +$ /srv/ego-current$ tail -f logs/wrapper.20210311.log |
| 128 | +INFO | jvm 1 | 2021/03/11 19:35:02 | 2021-03-11 19:35:02,492 [WrapperSimpleAppMain] INFO o.s.b.w.e.t.TomcatWebServer - Tomcat started on port(s): 8081 (http) with context path '' |
| 129 | +INFO | jvm 1 | 2021/03/11 19:35:02 | 2021-03-11 19:35:02,492 [WrapperSimpleAppMain] INFO o.s.b.w.e.t.TomcatWebServer - Tomcat started on port(s): 8081 (http) with context path '' |
| 130 | +INFO | jvm 1 | 2021/03/11 19:35:02 | 2021-03-11 19:35:02,497 [WrapperSimpleAppMain] INFO b.o.e.AuthorizationServiceMain - Started AuthorizationServiceMain in 22.659 seconds (JVM running for 24.385) |
| 131 | +``` |
| 132 | + |
| 133 | +## Auth Setup |
| 134 | +Now that Ego is up and running we want to configure the first user and application that can use Ego for Authorization. |
| 135 | + |
| 136 | +### Identity Provider |
| 137 | + |
| 138 | +For the identity provider of your choosing, find the relevant section in the `application.yml` configuration file and the client id and secret you have configured with that IdP. For example if Google is your IdP: |
| 139 | + |
| 140 | + |
| 141 | +```yml |
| 142 | +google: |
| 143 | + client: |
| 144 | + clientId: <cliend_id> |
| 145 | + clientSecret: <client_secret> |
| 146 | + accessTokenUri: https://www.googleapis.com/oauth2/v4/token |
| 147 | + userAuthorizationUri: https://accounts.google.com/o/oauth2/v2/auth |
| 148 | + clientAuthenticationScheme: form |
| 149 | + scope: |
| 150 | + - email |
| 151 | + - profile |
| 152 | + resource: |
| 153 | + userInfoUri: https://www.googleapis.com/oauth2/v3/userinfo |
| 154 | +``` |
| 155 | + |
| 156 | +### First Application |
| 157 | +Before users can login we need to setup the UI application inside of Ego. This can be done by setting `intialization.enabled` to true and configuring the rest of the settings to match the settings you will use in your UI application. |
| 158 | + |
| 159 | +```yml |
| 160 | +initialization: |
| 161 | + enabled: true # Set to true |
| 162 | + applications: |
| 163 | + - name: <name_of_your_ui_app> |
| 164 | + type: CLIENT |
| 165 | + clientId: <client_id_of_ui> |
| 166 | + clientSecret: <some_secret> |
| 167 | + redirectUri: <url to redirect to in UI, for Ego UI this would be root> |
| 168 | + description: Some description about this application # optional |
| 169 | +``` |
| 170 | + |
| 171 | +### First User |
| 172 | +Users by default do not have the `ADMIN` role and therefore cannot modify Ego or use the Ego UI. We want to allow the first user to login to be an ADMIN user. We can do that by using the following configuration in `application.yml`: |
| 173 | + |
| 174 | +```yml |
| 175 | +# Default values available for creation of entities |
| 176 | +default: |
| 177 | + user: |
| 178 | + # flag to automatically register first user as an admin |
| 179 | + firstUserAsAdmin: true |
| 180 | + type: ADMIN |
| 181 | + status: APPROVED |
| 182 | +``` |
| 183 | + |
| 184 | +### Putting it together. |
| 185 | +Now that we have updated our config we can restart Ego, and try to login via the UI. |
| 186 | +```shell |
| 187 | +bin/ego restart |
| 188 | +``` |
| 189 | + |
| 190 | +## Cleanup |
| 191 | + |
| 192 | +Assuming all is well, and the Ego database is properly configured and the first user and application are working, you will most likely want to disable the initialization of the first application and user. This means seetting the `firstUserAsAdmin` and `initialization.enabled` to `false`. |
| 193 | + |
| 194 | +Also, if you prefer to manage migrations yourself and not have Ego automatically apply them when you update Ego, disable the flyway migration as well. |
0 commit comments