Update documentation
This commit is contained in:
Denis Arh
+80
@@ -0,0 +1,80 @@
|
||||
# Corteza Command Line Interface
|
||||
|
||||
## General
|
||||
|
||||
You can choose from one of the four (4) app/service CLI entrypoints:
|
||||
|
||||
- system (`corteza-server-system`)
|
||||
- messaging (`corteza-server-messaging`)
|
||||
- compose (`corteza-server-compose`)
|
||||
- all-in-one monolith (`corteza-server`)
|
||||
|
||||
When system is build into a all-in-one binary or image,
|
||||
app-specific commands can be accessed under a sub-command with the
|
||||
same name as the app.
|
||||
|
||||
## Flags & environmental variables
|
||||
Command and application behaviour can be adjusted using flags and/or environmental
|
||||
variables. Flags have highest priority and override env. variables. Defaults that
|
||||
are pre-set internally are optimized for production mode.
|
||||
|
||||
Note that defaults shown under `--help` are overridden by value from the accompanying
|
||||
environemntal variable.
|
||||
|
||||
## How to run:
|
||||
|
||||
### Compile source files and run with `go run`
|
||||
|
||||
Source entrypoints can be found under `cmd/`:
|
||||
|
||||
```sh
|
||||
go run cmd/system/*.go [commands and flags]
|
||||
```
|
||||
|
||||
### Docker or Docker Compose
|
||||
|
||||
Docker images are built with handy presets for
|
||||
`ENTRYPOINT` and `CMD`. By default, `CMD` is set to `serve-api`.
|
||||
|
||||
See docker manual for more info.
|
||||
|
||||
```sh
|
||||
docker exec -it -rm corteza-server-system [commands and flags]
|
||||
```
|
||||
|
||||
## Base commands:
|
||||
|
||||
These commands are accessible from the base level (never
|
||||
wrapped under an app-sub-command) and always affect all apps.
|
||||
|
||||
### `provision`
|
||||
|
||||
Command `provision` Wraps 2 sub-commands:
|
||||
- `access-control-rules`
|
||||
Reset access control rules for Everyone and Administrator roles.
|
||||
- `migrate-database`
|
||||
Run database migration scripts
|
||||
|
||||
Both these commands are executed when you run `serve-api` command,
|
||||
after database is connected and before initialization. This behaviour can
|
||||
be changed with env variables.
|
||||
|
||||
## System specific commands & sub-commands
|
||||
|
||||
| Command | Subcommand | |
|
||||
| --- | --- | --- |
|
||||
| auth | auto-discovery | Auto discovers new OIDC client
|
||||
| auth | jwt | Generates new JWT for a user
|
||||
| auth | test-notifications | Sends samples of all authentication notification to receipient
|
||||
| roles | useradd | Add user to role
|
||||
| settings | auto-configure | Run autoconfiguration
|
||||
| settings | delete | Set value (raw JSON) for a specific key
|
||||
| settings | get | Get value (raw JSON) for a specific key
|
||||
| settings | import | Import settings as JSON from stdin or file
|
||||
| settings | list | List all
|
||||
| settings | set | Set value (raw JSON) for a specific key
|
||||
| users | add | Add new user
|
||||
| users | list | List users
|
||||
| users | password | Change user's password
|
||||
|
||||
See help (`--help`) under each (sub) command for details about additional flags and arguments.
|
||||
@@ -1,5 +1,7 @@
|
||||
# Authentication
|
||||
|
||||
If you are not already familiar with it, please read documentation about [Corteza Command Line Interface](CLI.md).
|
||||
|
||||
Corteza support a fixed set of standard OAuth 2 authentication providers
|
||||
(facebook, gplus, github and linkedin) and a arbitrary number of custom
|
||||
issuers (over OpenID Connect).
|
||||
@@ -12,9 +14,7 @@ Settings for external providers are stored under keys
|
||||
|
||||
Prop is one of: `key`, `secret`, `enabled`. OIDC settings also have `issuer` prop.
|
||||
|
||||
Example settings (`system settings list --prefix=auth.external`):
|
||||
|
||||
|
||||
Example settings (`settings list --prefix=auth.external`):
|
||||
```
|
||||
auth.external.callback-endpoint "https://your-corteza-system-api-backend/auth/external/%s/callback"
|
||||
auth.external.enabled true
|
||||
@@ -60,11 +60,11 @@ external authentication provider "openid-connect.corteza-iam" added
|
||||
|
||||
Corteza CLI comes with auto-discovery tool:
|
||||
```bash
|
||||
system external-auth auto-discovery name url
|
||||
external-auth auto-discovery name url
|
||||
```
|
||||
|
||||
```bash
|
||||
system external-auth auto-discovery corteza-iam https://satosa.didmos.crust.example.tld
|
||||
external-auth auto-discovery corteza-iam https://satosa.didmos.crust.example.tld
|
||||
```
|
||||
|
||||
This will autodiscover and autoconfigure new OIDC provider.
|
||||
@@ -74,5 +74,7 @@ Please note that this provider is disabled by default.
|
||||
|
||||
To enable it, run:
|
||||
```bash
|
||||
system settings key auth.external.providers.openid-connect.corteza-iam.enabled true
|
||||
settings key auth.external.providers.openid-connect.corteza-iam.enabled true
|
||||
```
|
||||
|
||||
Changing values requires system service restart.
|
||||
@@ -0,0 +1,50 @@
|
||||
# Corteza Setup
|
||||
|
||||
If you are not already familiar with it, please read documentation about [Corteza Command Line Interface](CLI.md).
|
||||
|
||||
## First steps
|
||||
|
||||
Corteza will pre-initialize itself to allow you to access all of it's features as quickly as possible.
|
||||
Internal authentication enabled, sign-up without email confirmation (in case you do not have your SMTP configured just
|
||||
yet)...
|
||||
|
||||
## Configuring system
|
||||
|
||||
### Configuring authentication
|
||||
|
||||
Review your current (auto-configure) settings with `settings list`:
|
||||
|
||||
```
|
||||
auth.external.enabled false
|
||||
auth.external.redirect-url "http://system.api.local.crust.tech/auth/external/%s/callback"
|
||||
auth.external.session-store-secret "PBVta4xKfQ0LIQEOtycxXqZZrGbZdTCuF4hw1cxrly1YA2AY5uO8a0SyY4Tbd1bk"
|
||||
auth.external.session-store-secure false
|
||||
auth.internal.enabled true
|
||||
auth.internal.password-reset.enabled true
|
||||
auth.internal.signup-email-confirmation-required false
|
||||
auth.internal.signup.enabled true
|
||||
auth.mail.from-address "change-me@example.tld"
|
||||
auth.mail.from-name "Corteza Team"
|
||||
```
|
||||
|
||||
| Key | Description |
|
||||
| ---- | ---- |
|
||||
| auth.external.enabled | Enable external authentication, see [ExternalAuth.md](ExternalAuth.md) for details
|
||||
| auth.external.redirect-url | Where to redirect after successful external authentication. This is the URL that you usually need to insert into your provider's auth app configuration page
|
||||
| auth.external.session-store-secret | Keep session values secret
|
||||
| auth.external.session-store-secure | Secure sessino store (set to false if not using TLS/HTTPS)
|
||||
| auth.internal.enabled | Enable/disable internal authentication (will users be able to use Corteza username and password to login)
|
||||
| auth.internal.password-reset.enabled | Enable password reset
|
||||
| auth.internal.signup-email-confirmation-required | Is email confirmation required on sign-up.
|
||||
| auth.internal.signup.enabled | Is sign-up enabled.
|
||||
| auth.mail.from-address | Who (email) is sending auth emails (password reset, email confirmation)
|
||||
| auth.mail.from-name | Who (name) is sending auth emails (password reset, email confirmation)
|
||||
|
||||
## Configuring messaging
|
||||
|
||||
_To be implemented_
|
||||
|
||||
|
||||
## Configuring corteza
|
||||
|
||||
_To be implemented_
|
||||
Reference in New Issue
Block a user