Quickstart
This guide installs the SOAJS gateway, the core services and the console on a Kubernetes cluster using the charts in soajs/soajs.helm. Everything is installed in the dashboard environment, in the soajs namespace.
Prerequisites
Section titled “Prerequisites”- A Kubernetes cluster and
kubectlconfigured for it. - Helm.
- Node.js, to run the key and password generator scripts in the chart repository.
- A clone of the chart repository:
git clone https://github.com/soajs/soajs.helm.gitcd soajs.helm1. Create the namespace
Section titled “1. Create the namespace”kubectl apply -f ./scripts/namespace.yamlIf the SOAJS infra service will manage the cluster for you, the repository also ships scripts/rbac.yaml. Review it before applying it: it binds the cluster-admin role to the default service account of the default namespace, and it uses the rbac.authorization.k8s.io/v1beta1 API, which current Kubernetes versions no longer serve (change it to rbac.authorization.k8s.io/v1).
2. Set your own values
Section titled “2. Set your own values”All charts read the shared values.yaml at the root of the repository. The values committed there are examples. Replace every credential, key and token with your own before installing; never deploy the committed ones.
| Key | What to set |
|---|---|
global.soajsConfig.domain |
Your domain. |
global.soajsConfig.apiPrefix |
Subdomain of the API (the console calls <apiPrefix>.<domain>). |
global.soajsConfig.sitePrefix |
Subdomain of the console (<sitePrefix>.<domain>). |
global.soajsConfig.kubernetes.ipAddr, .port, .token |
API server address, port and a service account token for your cluster. They are seeded into the infra record used by the infra service. |
global.soajsConfig.user.username, .email |
The console owner account. |
global.soajsConfig.user.hashedPassword |
The bcrypt hash of the owner password (see below). |
global.soajsConfig.keyPassword |
The secret used to encrypt external keys in the dashboard environment. |
global.soajsConfig.tenantInternalKey, .tenantExternalKey |
The console tenant’s internal and external key (see below). |
global.soajsConfig.mongo.servers |
MongoDB host(s). Leave the default to use the soajs-mongo chart. |
global.soajsNginxHttpPort, global.soajsNginxHttpsPort |
NodePorts used by soajs-ui-bridge-np. |
global.soajsDataExternalPort |
External port used by the MongoDB bridge charts. |
global.soajsDataPvcStorage |
Size of the MongoDB persistent volume claim. |
Generate the owner password hash
Section titled “Generate the owner password hash”Edit the password constant at the top of scripts/pwdGenerator/index.js, then run it. It prints the bcrypt hash to use as hashedPassword.
node scripts/pwdGenerator/index.jsGenerate the console tenant keys
Section titled “Generate the console tenant keys”Edit the keyPassword constant at the top of scripts/keyGenerator/index.js so it matches global.soajsConfig.keyPassword, then run it. It prints an internal key and an external key for the seeded console tenant and its DSBRD_GUEST package.
node scripts/keyGenerator/index.jsBoth scripts require the soajs npm package to be resolvable.
3. Install the data layer
Section titled “3. Install the data layer”helm install soajs-data ./soajs-data/ --namespace soajs -f ./values.yamlhelm install soajs-data-claim ./soajs-data-claim/ --namespace soajs -f ./values.yamlhelm install soajs-mongo ./soajs-mongo/ --namespace soajs -f ./values.yamlsoajs-data holds the initial data (environment record, catalog, console tenant, owner user) as ConfigMaps. soajs-mongo runs MongoDB and imports that data on first boot.
To reach MongoDB from outside the cluster, optionally install one of the bridges:
helm install soajs-mongo-bridge ./soajs-mongo-bridge/ --namespace soajs -f ./values.yaml# or, with a LoadBalancer servicehelm install soajs-mongo-bridge ./soajs-mongo-bridge-lb/ --namespace soajs -f ./values.yaml4. Install the gateway
Section titled “4. Install the gateway”Wait until MongoDB is ready, then:
helm install soajs-controller ./soajs-controller/ --namespace soajs -f ./values.yaml5. Install the core services
Section titled “5. Install the core services”Wait until the gateway is ready, then install each service:
helm install soajs-oauth ./soajs-oauth/ --namespace soajs -f ./values.yamlhelm install soajs-urac ./soajs-urac/ --namespace soajs -f ./values.yamlhelm install soajs-multitenant ./soajs-multitenant/ --namespace soajs -f ./values.yamlhelm install soajs-marketplace ./soajs-marketplace/ --namespace soajs -f ./values.yamlhelm install soajs-repositories ./soajs-repositories/ --namespace soajs -f ./values.yamlhelm install soajs-infra ./soajs-infra/ --namespace soajs -f ./values.yamlhelm install soajs-console ./soajs-console/ --namespace soajs -f ./values.yaml6. Install the console UI
Section titled “6. Install the console UI”Wait until the gateway is ready, then install the UI, either without TLS:
helm install soajs-ui ./soajs-ui/ --namespace soajs -f ./values.yamlor with TLS. Copy your certificate and key as tls.crt and tls.key into soajs-ui-ssl/resources first:
helm install soajs-ui ./soajs-ui-ssl/ --namespace soajs -f ./values.yamlExpose it once the UI is ready, with a NodePort or a LoadBalancer:
helm install soajs-ui-bridge ./soajs-ui-bridge-np/ --namespace soajs -f ./values.yaml# orhelm install soajs-ui-bridge ./soajs-ui-bridge-lb/ --namespace soajs -f ./values.yamlPoint <sitePrefix>.<domain> and <apiPrefix>.<domain> at the bridge and sign in to the console with the owner account you configured.
Check the gateway
Section titled “Check the gateway”Every SOAJS service exposes /heartbeat on its maintenance port, and the charts use it as the readiness probe. For the gateway the maintenance port is 5000:
kubectl -n soajs port-forward svc/dashboard-controller-v1-service 5000:5000curl http://localhost:5000/heartbeatRemove everything
Section titled “Remove everything”kubectl delete ns soajsNext: write your first service. See Helm charts for what each chart deploys.
