Skip to content

Commit

Permalink
Extend setup instructions in README
Browse files Browse the repository at this point in the history
  • Loading branch information
@daniel-va
daniel-va committed Apr 10, 2024
1 parent 256776a commit 4ee0768
Show file tree
Hide file tree
Showing 3 changed files with 127 additions and 44 deletions.
147 changes: 114 additions & 33 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,51 +1,132 @@
# SwissGeol Asset

## Setting up the development environment

## Development
The following components must be installed on the development computer:

✔️ Git
✔️ Docker
✔️ Node.js 20 LTS

The following steps must be carried out once:
### Setting Up the Development Environment
Follow these steps to set up the development environment on your local machine:
* [1. Configure Local Systems](#1-Configure-Local-Systems)
* [2. Configure the Asset Server](#2-Configure-the-Asset-Server)
* [3. Install Dependencies](#3-Install-Dependencies)
* [4. Build Local Systems](#4-Build-Local-Systems)
* [5. Initialize MinIO](#5-Initialize-MinIO)

#### 1. Configure Local Systems
Configure `development/.env` according to the [development services configuration](#Development-Services-Configuration).

#### 2. Configure the Asset Server
Create an empty copy of the [web server configuration](#Asset-Server-Configuration) as [`apps/server-asset-sg/.env.local`](apps/server-asset-sg/.env.local).
Configure the following variables:
* Set `AUTH_URL=http://localhost:8866`.
* Set `FRONTEND_URL=http://localhost:4200`.
* Set `DATABASE_URL=postgres://asset-swissgeol:asset-swissgeol@localhost:5432/postgres?schema=public`.
* Set `GOTRUE_JWT_SECRET` to the same value as in [`development/.env`](development/.env).
* Leave `OCR_URL` empty.
* Leave `OCR_CALLBACK_URL` empty.

#### 3. Install Dependencies
Install node modules:
```bash
npm run install
```

Decorate the Angular CLI with the Nx CLI:
```bash
npm run postinstall
```

#### 4. Build Local Services
Generate prisma-client for database-access:
```bash
cd apps/server-asset-sg/
ng gen-prisma-client
```

Build postgis-gotrue docker image:
```bash
cd development/images/db
docker build -t postgis-gotrue .
```

#### 5. Initialize MinIO
* [Start the development services](#Starting-the-Development-Environment).
* Open http://localhost:9001
* Sign in using the `STORAGE_USER` and `STORAGE_PASSWORD` of your development environment.
* Navigate to [Buckets](http://localhost:9001/buckets) and create a new bucket with the name `asset-sg`.
* Navigate to [the new bucket's browser](http://localhost:9001/browser/asset-sg) and create an empty folder with the name `asset-sg`.
* Navigate to [Configuration](http://localhost:9001/settings/configurations/region) and change the server region to `local`.
* Navigate to [Access Keys](http://localhost:9001/access-keys) and create a new access key.
* Open your Asset Server Configuration at [`apps/server-asset-sg/.env.local`](apps/server-asset-sg/.env.local) and make the following changes:
* `S3_REGION=local`
* `S3_ENDPOINT=http://localhost:9000`
* `S3_BUCKET_NAME=asset-sg`
* `S3_ASSET_FOLDER=asset-sg`
* `S3_ACCESS_KEY_ID` as your newly generated access key.
* `S3_SECRET_ACCESS_KEY` as your newly generated access key's secret.

1. Clone git repository whit `> git clone https://github.com/geoadmin/web-asset-swissgeol.git`.
2. Install all necessary modules with `web-asset-swissgeol> npm install`.
3. Decorate the Angular CLI with the Nx CLI `web-asset-swissgeol> npm run postinstall`.
4. Create prisma-client for database-access with `web-asset-swissgeol\apps\server-asset-sg> ng gen-prisma-client`.
5. Set environment variables for dockers in `web-asset-swissgeol\development\.env`
6. Set environment variables for assets-server in `web-asset-swissgeol\apps\server-asset-sg\.env.local`
7. Create local postgis-gotrue docker-image `development\images\db> docker build -t postgis-gotrue .`
8. Creating elastic-search index. Execute in Kibana (`http://localhost:5601/app/dev_tools#/console`) the commands fro file `web-asset-swissgeol\development\init\elasticsearch\index`. --> docker must be started (see below)
### Starting the Development Environment
Start development services:
```bash
cd development
docker compose up
```
Start the application:
```bash
npm run start
```

### Starting the development environment
### Local Services and Applications

1. Start docker with `web-asset-swissgeol\development>docker-compose up`.
2. Start asset-swissgeol app with `web-asset-swissgeol>npm run start`.
| 🔖App/Service | 🔗Link | 🧞User | 🔐Password |
|:-------------------------|:-------------------------------------------------|:-------------------------|:-------------------------|
| Assets (client) | [localhost:4200](http://localhost:4200/) | `[email protected]` | `swissgeol_assets` |
| Assets REST API (server) | [localhost:3333/api/](http://localhost:3333/api) | n/a | n/a |
| postgresSQL (docker) | localhost:5432 | .env `$DB_USER` | .env `$DB_PASSWORD` |
| Elasticsearch (docker) | [localhost:9200](http://localhost:9200) | n/a | n/a |
| Kibana (docker) | [localhost:5601](http://localhost:5601) | n/a | n/a |
| pgAdmin (docker) | [localhost:5051](http://localhost:5051/) | .env `$PGADMIN_EMAIL` | .env `$PGADMIN_PASSWORD` |
| MinIO (docker) | [localhost:9001](http://localhost:9001/) | .env `$STORAGE_USER` | .env `$STORAGE_PASSWORD` |
| smtp4dev (docker) | [localhost:5000](http://localhost:5000/) | n/a | n/a |

**The following services/applications are then available**

| 🔖App/Service | 🔗Link | 🧞User | 🔐Password |
| :-------------------------| :------------------------------------------------| :-----------------------| :-----------------------|
| Assets (client) | [localhost:4200](http://localhost:4200/) | `[email protected]`| `swissgeol_assets` |
| Assets REST API (server) | [localhost:3333/api/](http://localhost:3333/api) | n/a | n/a |
| postgresSQL (docker) | localhost:5432 | .env `$DB_USER` |.env `$DB_PASSWORD` |
| Elasticsearch (docker) | [localhost:9200](http://localhost:9200) | n/a | n/a |
| Kibana (docker) | [localhost:5601](http://localhost:5601) | n/a | n/a |
| pgAdmin (docker) | [localhost:5051](http://localhost:5051/) | .env `$PGADMIN_EMAIL` |.env `$PGADMIN_PASSWORD` |
| MinIO (docker) | [localhost:9001](http://localhost:9001/) | .env `$STORAGE_USER` |.env `$STORAGE_PASSWORD` |
| smtp4dev (docker) | [localhost:5000](http://localhost:5000/) | n/a | n/a |
# Configuration
## Asset Server Configuration
The file `apps/server-asset-sg/.env.local` configures secrets for the SwissGeol Asset server.
An empty template for the file can be found in [`apps/server-asset-sg/.env.template`](apps/server-asset-sg/.env.template).

### Creating elastic-search index
| Variable | Example | Description |
|----------------------|--------------------------------------------------------------------------------------------|------------------------------------------------------------|
| AUTH_URL | http://my.gotrue.example:8866 | URL of the GoTrue auth service. |
| FRONTEND_URL | http://assets.geo.admin.ch | Public URL of the SwissGeol Asset web client. |
| S3_REGION | euw-3 | Region of the S3 instance. |
| S3_ENDPOINT | http://compute-1.amazonaws.com | URL to the S3 instance. |
| S3_ACCESS_KEY_ID | AP6wpeXraSc0IH4d42IN | Access Key for the S3 instance. |
| S3_SECRET_ACCESS_KEY | fSx5Bfib0OeAyG1mwtslKA04Qj6oPStLcpnkACmF | Secret Key for the S3 instance. |
| S3_BUCKET_NAME | asset-sg | S3 bucket name. |
| S3_ASSET_FOLDER | asset-sg | Folder within the S3 bucket into which objects are stored. |
| DATABASE_URL | postgres://asset-swissgeol:asset-swissgeol@my.postgres.example:5432/postgres?schema=public | PostgreSQL access URL. |
| GOTRUE_JWT_SECRET | 18af41574b30be7539d8c3e45ccdeea9431cff6419cdce5cabc5f28cfb73e15c | JWT secret key for the GoTrue server. |
| OCR_URL | | Leave empty. |
| OCR_CALLBACK_URL | | Leave empty. |


## Development Services Configuration
The file `development/.env` configures secrets for the services used in local development.
An empty template for the file can be found in [`development/.env.template`](development/.env.template).

### Commands in development environment
> Make sure that your passwords have a minimal length of 8 and contain at combination of
> upper, lower and special characters. Some of the passwords will be checked for validity during startup.
| Action | Command | Description |
| :------| :------------------------------------| :-----------------------------------------|
| start | `web-asset-swissgeol> npm run start` | Starts asset-client and asset-api. |
| build | `web-asset-swissgeol> npm run build` | Builds asset-client and asset-api. |
| test | `web-asset-swissgeol> npm run test` | Executes tests all apps and libs. |
| lint | `web-asset-swissgeol> npm run lint` | Analyzes the code from all apps and libs. |
| Variable | Wert | Beschreibung |
|-------------------|----------|------------------------------------------|
| STORAGE_USER | _custom_ | Username for the MinIO container. |
| STORAGE_PASSWORD | _custom_ | Password for the MinIO container. |
| DB_USER | postgres | Username for the PostgreSQL container. |
| DB_PASSWORD | _custom_ | Password for the PostgreSQL container. |
| PGADMIN_EMAIL | _custom_ | Email for the PgAdmin container. |
| PGADMIN_PASSWORD | _custom_ | Password for the PgAdmin container. |
| GOTRUE_JWT_SECRET | _custom_ | JWT Secret Key for the GoTrue container. |
22 changes: 12 additions & 10 deletions apps/server-asset-sg/.env.template
View file
Original file line number Diff line number Diff line change
@@ -1,10 +1,12 @@
AUTH_URL=
FRONTEND_URL=
S3_REGION=
S3_ENDPOINT=
S3_ACCESS_KEY_ID=
S3_SECRET_ACCESS_KEY=
S3_BUCKET_NAME=
S3_ASSET_FOLDER=
DATABASE_URL=
GOTRUE_JWT_SECRET=
AUTH_URL=docker gotrue url 8866 (wird ersetzt durch IAM)
FRONTEND_URL=ng url
S3_REGION=local
S3_ENDPOINT=storage url 9000
S3_BUCKET_NAME=asset-sg
S3_ASSET_FOLDER=asset-sg
S3_ACCESS_KEY_ID=selber generieren in minio
S3_SECRET_ACCESS_KEY=selber generieren in minio
DATABASE_URL=db/01_roles + access url postgres
GOTRUE_JWT_SECRET=selber generieren, gleich wie in development
OCR_URL=
OCR_CALLBACK_URL=
2 changes: 1 addition & 1 deletion development/.env.template
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,4 +4,4 @@ DB_USER=
DB_PASSWORD=
PGADMIN_EMAIL=
PGADMIN_PASSWORD=
GOTRUE_JWT_SECRET=
GOTRUE_JWT_SECRET=

0 comments on commit 4ee0768

Please sign in to comment.