Merge pull request #232 from GispoCoding/215-add-ssh-instructions

215 add ssh instructions
GispoCoding · Mar 7, 2024 · 43887b6 · 43887b6
2 parents f9b5a60 + 7eafe84
commit 43887b6
Show file tree

Hide file tree

Showing 11 changed files with 88 additions and 0 deletions.
diff --git a/README.md b/README.md
@@ -12,6 +12,10 @@ HAME regional land use planning database compatible with national Ryhti data mod
   - [Database changes](#database-changes)
   - [Adding requirements](#adding-requirements)
 - [Data model](#data-model)
+- [Connecting the database](#connecting-the-database)
+  - [Creating SSH key pairs](#creating-ssh-key-pairs)
+  - [Opening a SSH tunnel to the server](#opening-a-ssh-tunnel-to-the-server)
+  - [Connecting the database from QGIS](#connecting-the-database-from-qgis)
 
 ## Architecture
 
@@ -77,3 +81,83 @@ To update requirements to latest versions:
 <!-- ## Data model
 
 [Database documentation](./database/dbdoc/README.md) -->
+
+## Connecting the database
+
+Connecting the database is done with the secure shell protocol (SSH). To be able to connect to the database, you will have to
+1. Create a SSH key pair on your computer (this has to be done only once)
+2. Have db admin add the public key to the server (this has to be done only once)
+3. Open a SSH tunnel on your computer (this has to be done each time)
+
+Detailed instructions to these steps are provided below.
+
+### Creating SSH key pairs
+
+Generation of the key pair can be done, for example, with a program called ssh-keygen (available also in Windows 10 and 11):
+
+- Open a command prompt (for example, open start menu and type 'cmd' and hit enter)
+- Type in the command prompt `ssh-keygen -t ed25519` and press enter. This will generate a key pair (using ed25519 algorithm).
+Here you could also spesify the name of the key file and passphrase to protect the key (see Fig.). If you accept the defaults, just press enter.
+
+By default the key pair is saved to `<your home folder>/.ssh/`: it contains your public key (id25519.pub), a text file which
+you have to provide to the database administrator, and the private key in file `id25519` (without the .pub suffix) which you MUST KEEP PRIVATE AND NOT SHARE IT WITH ANYONE!
+
+![screenshot of ssh key pair creation dialog](docs/img/ssh-keygen.png)
+
+
+### Opening a SSH tunnel to the server
+
+Once the administrator has added your public key to the server, you can connect to the database using ssh. You are provided also with the necessary connection parameters (host address, port etc.) and credentials, that are needed in the following commands. Open the command prompt again
+(type 'cmd' in the start menu) and in it, run the command:
+- `ssh -N -L 5433:<database server address>:<port number> -i "~/.ssh/<name of the private key file>" ec2-tunnel@<host address>`
+- Enter the passphrase for the key (if set) and hit enter. If no error messages appear, the tunnel is connected. Do not close the command prompt window, otherwise the SSH tunnel is disconnected.
+- Now you can connect to the database using `localhost` as the host and `5433` as the port. The details how to do this with
+different software are given in the following sections.
+- Additional tips: the connection can automatically terminate, for example, due to server rebooting or network issues (this is usually accompanied by a message, such as `client_loop: send disconnect: Connection reset`). If this happens, run again the previous command. You can usually access the history of the commands run in terminal window by up/down arrow keys on the keyboard. So pressing "up" key and then "Enter" should do the job. In case you want to close an open SSH tunnel, press `Ctrl+C`.
+
+### Connecting the database from QGIS
+
+The data is read from a PostgreSQL service named `postgres` with a QGIS authentication which id is `ryhtirw`. Here is a way to set up database connection in QGIS:
+
+1. Create a PostgreSQL service file for each environment (at the moment, there is only development environment). The file can be created, for example, with a text editor. Add the following with correct values for each environment:
+```ini
+[postgres]
+host=localhost
+port=5433
+dbname=hame-dev
+```
+Save the file to some folder, an example location could be `<your home folder>/hameconfig/`. Name the saved file for example `pg_service_hame_dev.conf` (yes, the suffix '.conf' is part of the file name). Do not save this file as a text file (with a suffix .txt), but instead choose 'All types' from the 'Save as type' dropdown menu.
+
+![screenshot of pgservice file made with notepad](docs/img/pg_servicefile_notepad.png)
+
+NOTE: the Postgres service file for the dev environment is also included in in this repository under the docs folder, so alternatively you can copy the file from the into a convenient location on your computer.
+
+2. Create a QGIS-profile for each environment. Name the profile for example `ryhti-hame-dev`. A new QGIS window will open to this profile, use that in the following.
+
+![screenshot of new profile menu](docs/img/qgis-new-profile.png)
+
+3. In QGIS settings add a `PGSERVICEFILE` environment variable and fill the file path of corresponding service file as a value.
+
+![screenshot of menu location](docs/img/qgis-settings.png)
+
+![screenshot of the setting dialog](docs/img/qgis-pgservicefile-environment-variable.png)
+
+4. Restart QGIS to make the environment variable to take effect.
+
+5. Create a authentication key to QGIS which ID is `ryhtirw`.
+
+NOTE: you may be prompted for setting a master password in QGIS, if not set earlier. If so, set master password and make sure to save it to a secure place for yourself. The master password is used to manage and access the saved authentication configurations in QGIS (for more information, see the [QGIS Documentation](https://docs.qgis.org/latest/en/docs/user_manual/auth_system/auth_overview.html)).
+
+![setting qgis master password](docs/img/qgis-auth-password.png)
+
+Now you can proceed with the database authentication details. As in step 3, open `Settings > Options` in QGIS and choose `Authentication` on the left panel. Click the green plus sign to add a new authentication configuration and fill in details as in the following image. It is important to use the authentication Id `ryhtirw` and database username and password here.
+
+![screenshot of the authentication dialog](docs/img/qgis-authentication.png)
+
+6. Create a new PostgreSQL connection
+
+![screenshot of the new connection menu](docs/img/qgis-new-connection.png)
+
+Add the necessary parameters as follows. You can also test the connection at this point and when done, press OK.
+
+![screenshot of the new connection dialog](docs/img/qgis-create-connection.png)
diff --git a/docs/img/pg_servicefile_notepad.png b/docs/img/pg_servicefile_notepad.png
diff --git a/docs/img/qgis-auth-password.png b/docs/img/qgis-auth-password.png
diff --git a/docs/img/qgis-authentication.png b/docs/img/qgis-authentication.png
diff --git a/docs/img/qgis-create-connection.png b/docs/img/qgis-create-connection.png
diff --git a/docs/img/qgis-new-connection.png b/docs/img/qgis-new-connection.png
diff --git a/docs/img/qgis-new-profile.png b/docs/img/qgis-new-profile.png
diff --git a/docs/img/qgis-pgservicefile-environment-variable.png b/docs/img/qgis-pgservicefile-environment-variable.png
diff --git a/docs/img/qgis-settings.png b/docs/img/qgis-settings.png
diff --git a/docs/img/ssh-keygen.png b/docs/img/ssh-keygen.png
diff --git a/docs/pg_service_hame_dev.conf b/docs/pg_service_hame_dev.conf
@@ -0,0 +1,4 @@
+[postgres]
+host=localhost
+port=5433
+dbname=hame-dev