Updating contribution draft

2026-05-07 08:56:42 +00:00 · 2022-04-20 15:18:13 +05:30
parent 5eb2ae4919
commit 0980f1e4e5
1 changed files with 66 additions and 125 deletions
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -14,37 +14,48 @@ If you’re looking to add a new feature, raise a new issue and start a discussi

 Below are all the details you need to know about the `RCloud Base` repo and get started with the development.

-## RCloud Base
+# Rcloud Base

 This repository contains all the rcloud-system components that are the backbone for ztka and gitops.

-### Prerequisites
+## Prerequisites

- Postgres: Primary database
- Ory Kratos: API for user management
- Elasticsearch: Storage for audit logs
+- [Postgres](https://github.com/postgres/postgres): Primary database
+- [Ory Kratos](https://www.ory.sh/kratos): API for user management
+- [Elasticsearch](https://www.elastic.co/elasticsearch/): Storage for audit logs

-You can use the bitnami/charts for postgres and elastic/helm-charts for elasticsearch.
+> You can use the
+> [bitnami/charts](https://github.com/bitnami/charts/tree/master/bitnami/postgresql/#installing-the-chart)
+> for postgres and
+> [elastic/helm-charts](https://github.com/elastic/helm-charts) for
+> elasticsearch.

-### Development setup
+## Development setup

-#### Using docker-compose
+### Using `docker-compose`

-Run following Docker Compose command to setup all requirements like Postgres db, Kratos etc. for the rcloud-base.
+Run following Docker Compose command to setup all requirements like
+Postgres db, Kratos etc. for the rcloud-base.

-This will start up postgres and elasticsearch as well as kratos and run the kratos migrations. It will also run all the necessary migrations. It also starts up a mail slurper for you to use Kratos.
+_This will start up postgres and elasticsearch as well as kratos and
+run the kratos migrations. It will also run all the necessary
+migrations. It also starts up a mail slurper for you to use Kratos._

-`docker-compose up -d`
+```bash
+docker-compose --env-file ./env.example up -d
+```

 Start rcloud-base:

-`go run github.com/RafayLabs/rcloud-base`
+```bash
+go run github.com/RafayLabs/rcloud-base
+```

-**Manual**
+### Manual

-**Start databases**
+#### Start databases

-**Postgres**
+##### Postgres

 ```bash
 docker run --network host \
@@ -53,7 +64,7 @@ docker run --network host \
    -it postgres
 ```

-**Elasticsearch**
+##### Elasticsearch

 ```bash
 docker run --network host \
@@ -63,134 +74,64 @@ docker run --network host \
    -it docker.elastic.co/elasticsearch/elasticsearch:8.0.0
 ```

-**Create the initial db/user**
+#### Create the initial db and user

-Scripts for admindb:
-
-```SQL
+```sql
 create database admindb;
 CREATE ROLE admindbuser WITH LOGIN PASSWORD '<your_password>';
 GRANT ALL PRIVILEGES ON DATABASE admindb to admindbuser;
 ```

-Now in the newly created db:
+#### Ory Kratos

-```sql
-CREATE EXTENSION IF NOT EXISTS "uuid-ossp";
-grant execute on function uuid_generate_v4() to admindbuser;
-```
+Install Ory Kratos using the [installation
+guide](https://www.ory.sh/docs/kratos/install) from Kratos
+documentation.

-Scripts for clusterdb:
-
-```sql
-CREATE database clusterdb;
-CREATE ROLE clusterdbuser WITH LOGIN PASSWORD '<your_password>';
-GRANT ALL PRIVILEGES ON DATABASE clusterdb to clusterdbuser;
-```
-
-Now in the newly created db:
-
-```sql
-CREATE EXTENSION IF NOT EXISTS "uuid-ossp";
-grant execute on function uuid_generate_v4() to clusterdbuser;
-```
-
-This will grant the necessary permission to the newly created user to run uuid_generate_v4()
-
-**Run application migrations**
-
-We use golang-migrate to perform migrations.
-Install golang-migrate
-
-`go install -tags 'postgres' github.com/golang-migrate/migrate/v4/cmd/migrate@latest`
-
-tags `postgres` is important as otherwise it compiles without postgres support
-
-You can refer to the guide for full details.
-Run migrations
-
-Example for admindb:
+Perform the Kratos migrations:

 ```bash
+export DSN='postgres://<user>:<pass>@<host>:<port>/admindb?sslmode=disable'
+kratos -c <kratos-config> migrate sql -e --yes
+```
+
+Start the Ory Kratos server using kratos config provided in
+[_kratos](./_kratos) directory.
+
+#### Run application migrations
+
+We use [`golang-migrate`](https://github.com/golang-migrate/migrate) to perform migrations.
+
+##### Install [`golang-migrate`](https://github.com/golang-migrate/migrate)
+
+```shell
+go install -tags 'postgres' github.com/golang-migrate/migrate/v4/cmd/migrate@latest
+```
+
+_`-tags 'postgres'` is important as otherwise it compiles without postgres support_
+
+You can refer to the [guide](https://github.com/golang-migrate/migrate/tree/master/cmd/migrate) for full details.
+
+##### Run migrations
+
+_It is required to perform Kratos migrations before this step._
+
+```shell
 export POSTGRESQL_URL='postgres://<user>:<pass>@<host>:<port>/admindb?sslmode=disable'
 migrate -path ./persistence/migrations/admindb -database "$POSTGRESQL_URL" up
 ```

-See cli-usage for more info.
+See [cli-usage](https://github.com/golang-migrate/migrate#cli-usage) for more info.

-### Development setup
+#### Start application

-Copy env.example to .env:
+Start rcloud-base:

-`cp env.example .env`
-
-Run following Docker Compose command to setup all requirements like Postgres db, Kratos etc. for the rcloud-base:
-
-`docker-compose up -d`
-
-Start rcloud-base server:
-
-`go run github.com/RafayLabs/rcloud-base`
-
-**Code Structure**
-
-The following section lists out the code structure for each of the 4 repos. Mention the folder structure along with its importance and what it is for.
-
-```
-components
-├── adminsrv
-│   ├── proto
-│   ├── server
-│   │   └── organization.go
-│   │   └── project.go
-│   ├── internal
-│   ├── pkg
-│   │   └── service
-│   ├── Dockerfile.adminsrv
-│   └── main.go
-│   └── buf.yaml
-│   └── buf.gen.yaml
-├── authz
-│   ├── proto
-│   ├── server
-│   │   └── authz.go
-│   ├── pkg
-│   │   └── service
-│   ├── Dockerfile.authz
-│   └── main.go
-│   └── buf.yaml
-│   └── buf.gen.yaml
-├── usermgmt
-│   ├── proto
-│   ├── server
-│   │   └── user.go
-│   │   └── role.go
-│   ├── internal
-│   ├── pkg
-│   │   └── service
-│   ├── Dockerfile.usermgmt
-│   └── main.go
-│   └── buf.yaml
-│   └── buf.gen.yaml
-├── cluster-scheduler
-│   ├── proto
-│   ├── server
-│   │   └── cluster.go
-│   ├── internal
-│   ├── pkg
-│   │   └── service
-│   ├── Dockerfile.cluster-scheduler
-│   └── main.go
-│   └── buf.yaml
-│   └── buf.gen.yaml
-├── common
-│   ├── proto
-│   ├── pkg
-│   └── buf.yaml
-│   └── buf.gen.yaml
+```bash
+go run github.com/RafayLabs/rcloud-base
 ```

-**Need Help?**
+## Need Help?

 We’re there for you - the best part of being a part of an open source community. If you are stuck somewhere or are facing an issue or just don’t know how to get started, feel free to let us know.