public/nplus
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Public Information

Browse Source
This commit is contained in:
Andreas Ahmann
2025-01-24 16:18:47 +01:00
commit 0bd2038c86
449 changed files with 108655 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

17
ai/jsonl/quickstart.jsonl Normal file
View File

@@ -0,0 +1,17 @@
{"chapter": "*nplus* Quickstart Guide", "level": 1, "text": "The charts are built in a way that they provide minimal functionality without any configuration, using default values.\n- If you want ingress, you have to configure the domain. Without the domain set, your charts will not have any default way to access them. However, you can still forward traffic to them or configure a *NodePort* or *LoadBalancer* manually.\n- If you want proper TLS, you need a certificate. Without the certificate provided, a self-signed certificate will secure your connection.\n- If you want specific storage, configure the storage class to use. Without it, you will get the default class for RWO and RWX.\nThis Quick Start example has nothing configured, so you will get:\n- No ingress, and\n- Default storage.\n"}
{"chapter": "Access to the *nplus* Subscription and the nscale License", "level": 1, "text": "You need access to:\n- The *nplus* Helm chart repository\n- The *nplus* container registry\n- The *nscale* license\n- The *nscale* container registry\nIn the next examples, we will use environment variables to access:\n```bash\nNPLUS_ACCOUNT=\"[your nplus subscription]\"\nNPLUS_TOKEN=\"[your nplus access token]\"\nNSCALE_ACCOUNT=\"[your account to access the Ceyoniq container registry]\"\nNSCALE_TOKEN=\"[the access token for above]\"\nNSCALE_LICENSE=\"[the path and license file to use]\"\n```\n"}
{"chapter": "The nplus helm repository", "level": 2, "text": "You can register the *nplus* Helm registry:\n```bash\nhelm repo add nplus https://git.nplus.cloud \\\n--username $NPLUS_ACCOUNT \\\n--password $NPLUS_TOKEN\nhelm repo update\n```\nYou should now be able to access the charts:\n```bash\n% helm search repo nplus --versions --devel\nNAME CHART VERSION APP VERSION DESCRIPTION\ngitea/nplus-application 9.1.1201-16 0.2.2 Application Chart\ngitea/nplus-application 9.1.1201-15 0.2.2 Application Chart\ngitea/nplus-application 9.1.1201-14 0.2.2 Application Chart\n...\n```\n> The `--devel` option gives you beta versions as well. Otherwise, you will only see release versions.\n"}
{"chapter": "The nscale license", "level": 2, "text": "Make sure you received an nscale license that fulfills the following criteria:\n- `Container: 1` - otherwise it will not allow to be run in a container environment\n- The Storage Layer `ServerID` *must not* be included in the license, as we cannot override it if it is fixed\n- `FullyQualifiedHostName: 0` - If this setting is *on*, the nstl will not work without the ServerID in the license\n- `DomainOnly: 1` - If this setting is *on*, the nstl will not work without the ServerID in the license\n- `hostname: \"*\"` - As hostnames are not really deterministic in Kubernetes, we need a license that allows the hosts to\nhave *any* name.\n- Make sure you have the storage adapter licensed, that you want to use (like S3, Azure BlobStore or Harddisk)\n- Optional: If you want High Availability with *nscale Server Storage Layer*, you need to have\n`DistributedService: 1`, otherwise the nstl instances can not communicate.\n"}
{"chapter": "*nplus* Cluster Resources", "level": 1, "text": "*nplus* also includes Cluster Resources (independent of Namespaces). These need to be installed first and globally.\n```bash\nhelm install nplus nplus/nplus-cluster\n```\nYou only need to perform this step once per Cluster, regardless of Environments/Namespaces.\n> If you don't want the *nplus* Helm application to appear in the current Namespace, you can install it as follows:\n```bash\nhelm template nplus nplus/nplus-cluster | kubectl apply -f -\n```\nAfter installing the cluster chart, you can test it by asking your cluster for deployed nscale resources:\n```bash\n$ kubectl get instance,component\nNo resources found in lab namespace.\n```\n*Instances* (also accessible via *nscale* or *nplus*) and *components* are custom resource definitions. Every Instance/Component installed will add an instance/component resource, and an *nplus operator* (which comes with the environment chart) will continuously check the instance/component health and report it via this command line or a web interface (see below).\n"}
{"chapter": "Create an *nplus* Environment", "level": 1, "text": "You can deploy *nplus* into a Kubernetes namespace. If you do not specify one, you will use the default one, which is fine for our test cluster. If you use namespaces, you can have multiple *nplus* environments in your cluster. Any environment can operate multiple *nplus* instances. Every *nplus* instance normally holds many components, each being *ReplicaSets* with multiple replicas.\nTo create a simple *nplus* environment without any additional features, deploy it into your new cluster:\n> By setting `--devel`, we are fetching the latest development version\n```bash\n% helm install --devel demo nplus/nplus-environment\nNAME: demo\nLAST DEPLOYED: Tue Dec 19 16:39:51 2023\nNAMESPACE: default\nSTATUS: deployed\nREVISION: 1\nTEST SUITE: None\nNOTES:\nnplus-environment 0.2.2-16 / 0.2.2\nThis Environment Chart provides a common config pool and administrative tools to operate all nplus instances in this namespace. There must be exactly one deployed instance of this environment chart. Without the environment, the instance and component charts will fail to deploy.\nTo uninstall, use\nhelm uninstall demo\nThe environment DAV Server is disabled.\nThe nstore Downloader is disabled.\nThe toolbox is disabled.\nProviding 10Gi of storage under the name \"conf\" of class \"default\"\n```\nNow you have an empty cluster ready to get a first instance deployment.\n"}
{"chapter": "Single Instance Mode", "level": 1, "text": "If you want to separate tenants on your system not only by instance but also by environment / namespace, you can run *nplus* in *single instance mode*.\nSIM (Single Instance Mode) lets you deploy your instance including all components of the environment in one single chart. Please see the [Instance README.md](../charts/instance/README.md) file for more details. This Quickstart Guide however is **not** using SIM.\n"}
{"chapter": "Deploy an *nplus* Instance", "level": 1, "text": "Before we can deploy the first *nplus* Instance, we need to add the Secrets for the registries and also the nscale license to the environment:\n```bash\nkubectl create secret docker-registry nscale-cr \\\n--docker-server=ceyoniq.azurecr.io \\\n--docker-username=$NSCALE_ACCOUNT \\\n--docker-password=$NSCALE_TOKEN\nkubectl create secret docker-registry nplus-cr \\\n--docker-server=cr.nplus.cloud \\\n--docker-username=$NPLUS_ACCOUNT \\\n--docker-password=$NPLUS_TOKEN\nkubectl create secret generic nscale-license \\\n--from-file=license.xml=$NSCALE_LICENSE\n```\n> Make sure the license key is called `license.xml` as that is used as the key in the charts.\nSecrets are namespace-dependent (one cannot access secrets from other namespaces), so we have to deploy them for every environment/namespace we use in our cluster.\nThere are multiple ways of deploying an *nplus* Instance, the easiest one is by simply calling the helm install on the command line:\n```bash\nhelm install --devel myinstance nplus/nplus-instance\n```\nYou can check the status of the instance using:\n```bash\n"}
{"chapter": "kubectl get instance", "level": 1, "text": "NAME HANDLER VERSION TENANT STATUS\nmyinstance Helm 9.1.1501 default starting\n```\nAnd the component status with:\n```bash\n"}
{"chapter": "kubectl get components", "level": 1, "text": "NAME INSTANCE COMPONENT TYPE VERSION STATUS\ncomponent.nplus.cloud/myinstance-nstl myinstance nstl nstl 9.1.1200 healthy\ncomponent.nplus.cloud/myinstance-rs myinstance rs rs 9.1.1300 healthy\ncomponent.nplus.cloud/myinstance-database myinstance database database 15 healthy\ncomponent.nplus.cloud/myinstance-nappl myinstance nappl\ncore 9.1.1501 healthy\ncomponent.nplus.cloud/myinstance-web myinstance web web 9.1.1500 healthy\ncomponent.nplus.cloud/myinstance-administrator myinstance administrator administrator 9.1.1500 healthy\n```\nYou can check the log files of the *Application Layer* for instance by typing:\n```bash\n"}
{"chapter": "kubectl logs -l nplus/instance=myinstance,nplus/component=nappl", "level": 1, "text": "```\n> Notice the locator in the logs example: Instead of telling kubectl the name of the pod or rs, we use locators because there may be multiple instances of these pods later, and we want to see all logs in one go (or have ELK, EFK, Splunk, or anything similar to do that for us).\n"}
{"chapter": "Adding an Ingress", "level": 1, "text": "We need to know the available ingressClasses in our new Kubernetes Cluster, so we check that:\n```bash\n"}
{"chapter": "kubectl get ingressclass", "level": 1, "text": "NAME CONTROLLER PARAMETERS AGE\npublic k8s.io/ingress-nginx <none> 72m\nnginx k8s.io/ingress-nginx <none> 72m\n```\n*Microk8s* comes with the most common classes, which both point to the same controller (in this case, nginx). *public* is indeed the default class for *nplus*. So we do not need to set that; it is already configured. We just need to tell the *nplus* instance to use a Domain for the ingress:\n```bash\nhelm upgrade --devel \\\n--set global.ingress.domain=myinstance.demo.nplus.cloud \\\nmyinstance nplus/nplus-instance\n```\nThis now activates an ingress for [https://myinstance.demo.nplus.cloud/nscale_web](https://myinstance.mydomain.demo.nplus.cloud/nscale_web). The easiest and fastest is probably to add the IP to the server into your `/etc/hosts` file.\n"}
{"chapter": "Adding a Certificate", "level": 1, "text": "After just adding the domain, the browser will complain about the self-signed certificate. You can easily add your certificate into the secret `myinstance.demo.nplus.cloud-tls`, which has been created for you.\nHowever, the canonical way is to have *cert-manager* or a similar tool take care of your certificates and have them generated by your CA or *Lets Encrypt* or similar.\nIf you have a running instance of cert-manager, you just need to specify the issuer:\n```bash\nhelm upgrade --devel \\\n--set global.ingress.domain=myinstance.demo.nplus.cloud \\\n--set global.ingress.issuer=nplus-issuer \\\nmyinstance nplus/nplus-instance\n```\nIn this example, *nplus-issuer* is the name of the issuer we created during the [Addons Guide](docs/addons.md).\nYou can now access your new instance with [https://myinstance.demo.nplus.cloud](https://myinstance.demo.nplus.cloud) or whatever domain you might have for it.\n"}
{"chapter": "Adding an Application", "level": 1, "text": "Trying to log in to your new instance will probably give you an error message:\n![Web Error](assets/noda.png)\nSo we need to create the Document Area and maybe even add some Business App.\nBusiness Apps can be installed from the *pool*. The *pool* is a shared file system, the *nplus environment* exposes to the *nplus instances*. This is handled by the *toolbox* feature, which is disabled by default.\nSo first, we enable it:\n```bash\nhelm upgrade --devel \\\n--set toolbox.enabled=true \\\n--set nstoreDownloader.enabled=true \\\ndemo nplus/nplus-environment\n```\nAnd while we are at it, we also enable the *nstore downloader*, which is a job running in the background automatically downloading the latest business app installer from Ceyoniq.\nIt will take a couple of minutes before the apps are downloaded by the job. You can peek into the folder:\n```bash\nkubectl exec --stdin --tty nplus-toolbox-0 -- ls -lais /conf/pool\n```\nThe Business Apps alone will not install without a proper *App-Installer*. You can download it from the Ceyoniq Service Portal. Once you have it, upload it to the pool as well:\n```bash\nkubectl cp app-installer-9.0.1202.jar nplus-toolbox-0:/conf/pool\n```\nNow, you have everything you need to get an App up:\n- The App Installer\n- Apps\nThe Command Line for installing our *myinstance* Instance is getting quite large, so here is how to put all that into one (or more) yaml files. Create a yaml called *myinstance.yaml* and add the following (which is identical to the command lines above plus the App Install)\nNotice that the domain is using a template function in this example. This adds the ability to reuse the same yaml for multiple instances. We will reuse it for the ArgoCD sample during the [ArgoCD Quickstart Guide](quickstart-argo.md).\n```yaml\nglobal:\ningress:\ndomain: \"{{ .Release.Name }}.demo.nplus.cloud\"\nissuer: \"nplus-issuer\"\ncomponents:\napplication: true\napplication:\nappInstaller: \"/pool/app-installer-9.0.1202.jar\"\ndocAreas:\n- id: \"SBS\"\nname: \"DocArea with SBS\"\ndescription: \"This is a sample DocArea with the SBS Apps installed\"\napps:\n- \"/pool/nstore/bl-app-9.0.1202.zip\"\n- \"/pool/nstore/gdpr-app-9.0.1302.zip\"\n- \"/pool/nstore/sbs-base-9.0.1302.zip\"\n- \"/pool/nstore/sbs-app-9.0.1302.zip\"\n- \"/pool/nstore/tmpl-app-9.0.1302.zip\"\n- \"/pool/nstore/cm-base-9.0.1302.zip\"\n- \"/pool/nstore/cm-app-9.0.1302.zip\"\n- \"/pool/nstore/hr-base-9.0.1302.zip\"\n- \"/pool/nstore/hr-app-9.0.1302.zip\"\n- \"/pool/nstore/pm-base-9.0.1302.zip\"\n- \"/pool/nstore/pm-app-9.0.1302.zip\"\n- \"/pool/nstore/sd-base-9.0.1302.zip\"\n- \"/pool/nstore/sd-app-9.0.1302.zip\"\n- \"/pool/nstore/kon-app-9.0.1302.zip\"\n- \"/pool/nstore/kal-app-9.0.1302.zip\"\n- \"/pool/nstore/dok-app-9.0.1302.zip\"\n- \"/pool/nstore/ts-base-9.0.1302.zip\"\n- \"/pool/nstore/ts-app-9.0.1302.zip\"\n- \"/pool/nstore/ocr-base-9.0.1302.zip\"\n```\nThis yaml will:\n- Switch on the *application chart*, which will install Apps\n- Tell the application to use the App Installer we just uploaded\n- Define a new Document Area (*SBS*) to be created\n- And then finally, in this example, we install SBS completely based on the Apps we downloaded from *nstore*. Make\nsure your license covers SBS; otherwise, it will fail.\nThen, you can upgrade *myinstance* with the new settings:\n```bash\nhelm upgrade \\\n--values myinstance.yaml \\\nmyinstance nplus/nplus-instance\n```\n> You can specify multiple values files, so it is fine to have one for the environment settings, one for the instance settings, and a third one for the application settings. This way, you can easily create multiple instances with shared settings to have maximum re-usage among instances.\nYou can follow the application installer using:\n```bash\n"}
{"chapter": "kubectl logs -l job-name=myinstance-application -f", "level": 1, "text": "...\nDefaulted container \"run\" out of: run, wait-for-myinstance-nappl (init), copy-conf (init)\n2024-03-11 16:08:33,918 [main] INFO com.ceyoniq.nscale.appconfig.NscaleServerWriter - updating CustomConfiguration Procurement to 9.0.1302\n2024-03-11 16:08:33,993 [main] INFO com.ceyoniq.nscale.appconfig.NscaleServerWriter - finished app configuration..\nApp '/pool/pm-app-9.0.1302.zip' successfully installed\ninstall App /pool/sd-base-9.0.1302.zip into SBS\nTry installation of app zip: /pool/sd-base-9.0.1302.zip\n2024-03-11 16:08:36,406 [main] INFO com.ceyoniq.nscale.businessapps.sd.base.Installer - App ('sd-app') not installed yet. Installing version 9.0.1302\n2024-03-11 16:08:43,031 [main] INFO com.ceyoniq.nscale.appconfig.NscaleMapper.Icons - Installing icons..\n2024-03-11 16:08:43,033 [main] INFO com.ceyoniq.nscale.appconfig.NscaleMapper.Folders - Installing Folders..\n2024-03-11 16:08:43,037 [main] INFO com.ceyoniq.nscale.appconfig.NscaleMapper.FolderTemplates - Installing FolderTemplates..\n...\ndone config scripts.\nrunning application scripts\nRunning /application/*.sh\ndone application scripts.\n```\nOnce it is done, close your browser (to make sure you open a fresh session) and try to log in again:\n![&nbsp](assets/web.png)\n> Admin does not have any SBS user roles by default; that is why you do not see any Apps after login.\n"}
{"chapter": "Further Reading", "level": 1, "text": "- You will find more complex examples in the [samples directory](/samples).\n- Please have a look at the README.md of the charts to explore more configuration options:\n```bash\nhelm show readme nplus/nplus-environment\nhelm show readme nplus/nplus-instance\n```\n- There are also charts for every component used by the instance umbrella chart.\n- You can also start configuring your instance by retrieving and altering the values.yaml of the chart.\n```bash\nhelm show values --devel nplus/nplus-instance > myinstance.yaml\n```\nThen edit this file. When you are done, apply it:\n```bash\nhelm upgrade --devel \\\n-f myinstance.yaml \\\nmyinstance nplus/nplus-instance\n```\n> Please be aware that the umbrella `values.yaml` does **not** contain all possible configuration options of the child charts.\n"}