You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
This project is under active development. The goal is to provide an orchestration and scheduling platform for earthquake forecast models.
12
12
13
13
For v0 of the project, see the [gitlab repository](https://gitlab.seismo.ethz.ch/indu/rt-ramsis)
14
14
15
-
## Installation
15
+
## 2. Installation
16
16
This installation instruction is merely a recommendation for a user of the software. Depending on your preferences and knowledge, you are free to choose a different setup.
17
17
18
+
To use the software, you need to have a correctly configured Prefect Server installation as well as a PostgreSQL database. You can install them using Docker Compose as described in section [2.1](#21-installation-of-the-services). If there is already such an installation provided, you can skip to section [2.2](#22-install-hermes).
18
19
19
-
### 1. Install Docker
20
+
21
+
### 2.1 Installation of the services.
22
+
23
+
#### 2.1.1 Install Docker
20
24
Follow the instructions [here](https://docs.docker.com/get-docker/)
21
25
22
-
### 2. Create a working directory with a Python virtual environment
23
-
Required Python version is 3.12
26
+
####2.1.2 Clone the repository
27
+
First you need to clone the repository. This will create a folder called `rt-hermes` in your current directory.
The `.env` file is used to configure the Prefect Server and the PostgreSQL database. It contains sensitive information such as passwords and connection strings. You can create a copy of the example file with the following command:
As a quick test setup, the configuration works as is, but is not secure. Please change the credentials, ports and connection strings in the .env file.
35
39
36
-
### 4. Install the required Python packages
40
+
#### 2.1.4 Create the Docker services
41
+
You can now create the Docker services for the Prefect Server and the PostgreSQL database using the following commands:
37
42
```
38
-
pip install -e src/hermes
43
+
docker compose -f compose-prefect.yaml up -d
44
+
docker compose --env-file .env -f compose-database.yaml up -d
39
45
```
46
+
You can now access the Prefect Server at [http://localhost:4200](http://localhost:4200) and the webservice at [http://localhost:8000/docs](http://localhost:8000/docs).
47
+
48
+
49
+
### 2.2 Install HERMES
40
50
41
-
### 5. Start the Prefect Service
42
-
After the successful installation of Docker, you can start the Prefect service with the following command:
51
+
#### 2.2.0 Prerequisites
52
+
If you already followed Section [2.1](#21-installation-of-the-services), you can create a new folder next to the cloned `rt-hermes` repository to create your project.
53
+
If you have a Service installation provided, but would like to use the examples provided in the repository, you can still clone the repository to get the examples and the template env file:
43
54
```
44
-
docker compose -f src/hermes/compose-prefect.yaml up -d
If you want to set a more secure password, you can pass it as an environment variable:
57
+
58
+
#### 2.2.1 Install Python and a virtual environment
59
+
It is strongly recommended to use a virtual environment. This will ensure that the dependencies are isolated from your system Python installation.
47
60
```
48
-
PREFECT_PASSWORD=mytopsecretpass docker compose -f src/hermes/compose-prefect.yaml up -d
61
+
mkdir hermes-project && cd hermes-project
62
+
python3 -m venv env # python3.12 is required
63
+
source env/bin/activate
64
+
pip install -U pip wheel setuptools
49
65
```
50
66
51
-
### 5. Configure environment file
67
+
#### 2.2.2 Install HERMES
68
+
Install Hermes from the Python Package Index
52
69
```
53
-
cp src/hermes/.env.example .env
70
+
pip install rt-hermes
54
71
```
55
-
As a quick test setup, the configuration works as is, but is not secure. Please change the credentials, ports and connection strings in the .env file.
56
72
57
-
### 6. Start the HERMES database services
73
+
### 2.2.3 Configure the environment file
74
+
For HERMES to find the correct Prefect Server and PostgreSQL database, you need to create a `.env` file in the root of your project. You can use the example file provided in the repository:
75
+
58
76
```
59
-
docker compose --env-file .env -f src/hermes/compose-database.yaml up -d
77
+
# Assuming you have cloned the repository into the current directorys parent
78
+
cp ../rt-hermes/.env.example .env
60
79
```
80
+
Use the credentials defined in section [2.1](#21-installation-of-the-services) or the ones provided to you by your admin.
81
+
82
+
#### 2.2.4 Use the CLI
83
+
The main usage of HERMES is currently via CLI
84
+
61
85
62
-
### 7. Install the models
86
+
#### 2.2.5 Install the models
87
+
To run models, you need to have them installed locally. You can, for example, clone them into a subdirectory and install from there.
You can start with an example configuration and data to get a feel for how HERMES works. The example configuration is located in the `examples/induced` folder. You can copy it to your project directory using the following command, assuming again you have the repository cloned in the parent directory:
72
101
```
73
-
cp -r src/hermes/examples .
102
+
cp -r ../rt-hermes/examples .
74
103
```
75
104
Update the absolute path `fdsnws_url` in the `examples/induced/forecastseries.json` file to the path of the `examples/induced` folder.
76
105
77
-
### 9. Initialize the database
106
+
### 3.2 Initialize the database
78
107
```
79
108
hermes db init
80
109
```
81
110
This only needs to be done once. In case you want to delete all data and start from scratch, you can run `hermes db purge` and then `hermes db init` again.
@@ -94,13 +123,13 @@ Most setting should be self-explanatory, but more information can be found in th
94
123
95
124
A more detailed of the InjectionPlan configuration can be found [here](https://github.com/swiss-seismological-service/hermes/blob/main/docs/injectionplan.md).
96
125
97
-
### 11. Run a single forecast using the CLI
126
+
### 3.4 Run a single forecast using the CLI
98
127
```
99
128
hermes forecasts run fs_induced --start 2022-04-21T15:00:00 --end 2022-04-21T18:00:00 --local
100
129
```
101
130
This starts a single forecast directly on the local machine.
102
131
103
-
### 12. (Optional) Schedule forecasts or execute "replays".
132
+
### 3.5 (Optional) Schedule forecasts or execute "replays".
104
133
To use advanced features like scheduling, it is necessary to start a process which "serves" the forecastseries.
__Note__ that a schedule can either lie in the past, the future, or both. The `catchup` command will only execute forecasts in the past, while the service will automatically execute forecasts in the future.
131
160
132
-
## Debugging
161
+
### 3.6 Debugging
133
162
To view the forecasts and modelruns, currently only the webservice is available. The available endpoints are listed in the [API documentation](http://localhost:8000/docs).
134
163
135
-
To view the status of the latest forecasts, you can navigate to the following URL: [http://localhost:8000/v2/forecasts](http://localhost:8000/v2/forecasts).
164
+
A quick description of the way to traverse the API is as follows:
165
+
To view the `Projects`, you can navigate to the following URL: [http://localhost:8000/v1/projects](http://localhost:8000/v1/projects). Copy the `oid` of the project you'd like to access.
136
166
137
-
To more easily debug the models, you can download the exact configuration and input files the modelrun used. You need copy the `oid` of the modelrun you'd like to download and then navigate to the following URL: `http://localhost:8000/v2/modelruns/{oid}/input`
167
+
To find the correct `Forecastseries`, you can navigate to the following URL: [http://localhost:8000/v1/projects/<project_oid>/forecastseries](http://localhost:8000/v1/projects/<project_oid>/forecastseries). Again, copy the `oid` of the `ForecastSeries`.
138
168
139
-
## Results
169
+
To view the `Forecasts` and `ModelRuns`, you can navigate to the following URL: [http://localhost:8000/v1/forecastseries/<forecastseries_oid>/forecasts](http://localhost:8000/v1/forecastseries/<forecastseries_oid>/forecasts).
140
170
141
-
The results of the modelruns can be directly downloaded from the webservice. This API is still under development and will be improved in the future. The results can be downloaded from the following URL: `http://localhost:8000/v2/modelruns/{oid}/result`. In the future, a more user-friendly interface will be provided.
171
+
Once you have the `oid`of the models, you can use that to more easily debug the models. You can download the exact configuration and input files the modelrun used. Navigate to the following URL: [http://localhost:8000/v1/modelruns/<modelrun_oid>/input](http://localhost:8000/v1/modelruns/<modelrun_oid>/input) to download the input files.
142
172
173
+
### 3.7 Results
143
174
144
-
## Reinstall
145
-
If you want to update the project and would like a clean install or/and don't care about the existing data, you can do so by running the following commands:
175
+
The results of the modelruns can be directly downloaded from the webservice. This API is still under development and will be improved in the future. The results can be downloaded from the following URL: [http://localhost:8000/v1/modelruns/<modelrun_oid>/results](http://localhost:8000/v1/modelruns/<modelrun_oid>/results).
146
176
147
-
To update, first go to the `src/hermes` folder and pull the latest changes. Then force-reinstall the dependencies to be sure that the correct versions are installed:
177
+
### 3.8 Python Client
148
178
179
+
A Python client library is provided for easier access to the RT-HERMES data and results. It can be installed using pip:
149
180
```bash
150
-
cd src/hermes
151
-
git pull
152
-
pip install -e src/hermes --force-reinstall
153
-
cd ../..
181
+
pip install hermes-client
154
182
```
183
+
A documentation is available [here](https://github.com/swiss-seismological-service/hermes-client.git)
155
184
156
-
Optionally do the same for the models.
157
185
158
-
Update the prefect docker containers:
186
+
## 4 Update
187
+
### 4.1 Update the services
188
+
Inside the cloned repository folder, update the prefect docker containers:
159
189
160
190
```bash
161
-
docker compose -f src/hermes/compose-prefect.yaml down -v
docker compose --env-file .env -f src/hermes/compose-database.yaml up -d
171
-
```
172
-
173
-
Now update the database:
174
-
```bash
197
+
docker compose -f compose-database.yaml up -d
175
198
hermes db upgrade
176
199
```
177
200
178
-
##Update
179
-
If you want to update the project and would like to keep the existing data, you can do so by running the following commands:
201
+
### 4.2 Update the library
202
+
If you want to update the library, you can do so by running the following command inside your virtual environment:
180
203
181
-
To update, first go to the `src/hermes` folder and pull the latest changes. Then force-reinstall the dependencies to be sure that the correct versions are installed:
204
+
```bash
205
+
pip install -U rt-hermes
206
+
```
182
207
208
+
If you need to update the hermes database too (if your admin has not done that already), you can run the following command:
183
209
```bash
184
-
cd src/hermes
185
-
git pull
186
-
pip install -e src/hermes --force-reinstall
187
-
cd ../..
210
+
hermes db upgrade
188
211
```
189
212
190
-
Optionally do the same for the models.
213
+
### 4.3 Reinstall the services
191
214
192
-
Update the prefect docker containers:
215
+
If you want to update the services and would like a clean install or/and don't care about the existing data, you can do so by completely removing the existing containers and volumes, pulling the latest changes, and then starting the services again.
193
216
194
217
```bash
218
+
docker compose -f src/hermes/compose-prefect.yaml down -v
0 commit comments