diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 67231ab..be62aa5 100644 --- 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 ''; 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 ''; -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://:@:/admindb?sslmode=disable' +kratos -c 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://:@:/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.