servala/servala-portal
3
0
Fork 0
Code Issues 21 Pull requests 5 Projects 2 Releases Packages 2 Activity Actions

document models and admin
All checks were successful
Build and Deploy Staging / build (push) Successful in 1m12s
Details
Build and Deploy Antora Docs / build (push) Successful in 40s
Details
Tests / test (push) Successful in 24s
Details
Build and Deploy Staging / deploy (push) Successful in 10s
Details
Build and Deploy Antora Docs / deploy (push) Successful in 5s
Details

Browse source
This commit is contained in:
Tobias Brunner 2025-04-15 10:36:08 +02:00
parent fa3eb7c4fc
commit c4f7c8df69
No known key found for this signature in database
7 changed files with 860 additions and 56 deletions
Download patch file Download diff file Expand all files Collapse all files

59
docs/modules/ROOT/pages/web-portal-admin.adoc Normal file
View file

@ -0,0 +1,59 @@
= Web Portal Admin
The administration of the web portal happens with Django Admin.
[TIP]
====
* Production: https://portal.servala.com/admin[portal.servala.com^]
* Staging: https://staging.portal.servala.com/admin[staging.portal.servala.com^]
====
== Service Catalog and Control-Plane Models
image::portal-service-relations.drawio.svg[]
Service::
The software service, top-level, categorized. +
_Examples_: PostgreSQL, Redis, GitLab. +
Admin: https://staging.portal.servala.com/admin/core/service/[staging^], https://portal.servala.com/admin/core/service/[prod^]
Service Definition::
A correlation between a specific managed service offering with the API definition on the control-planes. It tells the Portal which Kubernetes API implements a managed service. +
_Example_: "Forgejo by VSHN" is implemented by GVK `vshn.appcat.vshn.io/v1/VSHNForgejo` on the control-planes. +
Admin: https://staging.portal.servala.com/admin/core/servicedefinition/[staging^], https://portal.servala.com/admin/core/servicedefinition/[prod^]
Service Offering::
The service offering is the glue which connects a service with a service provider, the control-planes with the service definitions and plan information. It essentially tells the Portal which managed service is available on which control-plane with which specific configuration. It relates to "ControlPlane CRD" which is a correlation between "Service Offering", "Control Plane" and "Service Definition".
_Example_: "Forgejo at Hetzner Cloud" which makes the Service "Forgejo" available at Hetzner Cloud and through "ControlPlane CRDs" it defines which service definition is available in which control-plane at Hetzner Cloud. It also specifies plans with features, pricing and terms. +
Admin: https://staging.portal.servala.com/admin/core/serviceoffering/[staging^], https://portal.servala.com/admin/core/serviceoffering/[prod^]
== Models
In addition to the models described in <<Service Catalog and Control-Plane Models>>, the following core models exist:
Cloud Providers::
Cloud providers where service instances can be provisioned at.
Control Planes::
Connections to Kubernetes API servers. Each control-plane represents a zone at a cloud provider.
Organizations::
The main multi-tenant object.
Organization Memberships::
Defines organization memberships including the roles in an organization.
Organization Origins::
The origin of an organization. Where the organization is coming from, influences e.g. access to control-planes or service offerings.
Billing Entities::
Billing contacts for Organizations - this is not further implemented yet.
Plans::
Plans for service offerings.
Service Categories::
Allows to categorize services.
Service Instances::
Service instances provisioned on control-planes.

30
docs/modules/ROOT/pages/web-portal-controlplanes.adoc Normal file
View file

@ -0,0 +1,30 @@
= Web Portal Control-Planes
Each control-plane represents a zone at a cloud provider. It's a dedicated Kubernetes API endpoint running the Servala control-plane.
To register a control-plane, a service account with appropriate permissions is required on the Kubernetes API server.
Example:
[source,bash]
----
# Create service account
kubectl -n kube-system create sa servala-portal
# Create long-lived token for service account
kubectl -n kube-system apply -f - <<EOF
apiVersion: v1
kind: Secret
metadata:
name: servala-portal-token
annotations:
kubernetes.io/service-account.name: servala-portal
type: kubernetes.io/service-account-token
EOF
# Grant access
kubectl create clusterrolebinding servala-portal-admin --clusterrole=cluster-admin --serviceaccount=kube-system:servala-portal
# Retrieve token
kubectl ksd -n kube-system get secret servala-portal-token -o yaml
----

64
docs/modules/ROOT/pages/web-portal-planning.adoc Normal file
View file

@ -0,0 +1,64 @@
= Web Portal Planning
image::web-portal-arch.drawio.svg[]
The Servala Web Portal is the central multi-tenant multi-service-provider aggregation and self-service main entrypoint for Servala.
Servala is the brand for the product formerly known as "VSHN Application Marketplace".
It offers self-service provisioning, multi-tenancy via organizations, access control, and provides central management access over multi cloud providers and the instances running this way.
The portal is a web application consuming various third party APIs to provide an aggregated and opinionated view.
External resources to read about it:
* http://vshn.ch/marketplace[vshn.ch Website^]
* https://products.vshn.ch/marketplace/index.html[VSHN products site^]
The source code can be found on the https://servala.app.codey.ch/servala/servala-portal[Servala Codey instance^].
== Technology Stack
We choose:
* Python https://docs.djangoproject.com/en/dev/internals/release-process/#term-Long-term-support-release[Django LTS^]
* PostgreSQL as database backend
* https://gunicorn.org/[Gunicorn^] Python WSGI HTTP Server
* https://caddyserver.com/[Caddy^] for serving static files and WSGI, or https://whitenoise.readthedocs.io/en/latest/[WhiteNoise^] (TBD)
* https://docs.astral.sh/uv/[Astral uv^] for Python project, dependency and build management
* https://htmx.org/[htmx] for the dynamic part in the frontend
* https://getbootstrap.com/[Bootstrap 5] for styling the frontend
A complete reasoning for this stack is available in https://vshnwiki.atlassian.net/wiki/spaces/VSHNPM/pages/402718747/Self-Service+Marketplace+Web+Application[our wiki^] (internal page).
== Development Paradigms
Keep usage of third-party dependencies low::
Every external dependency adds a burden on the maintenance of the application.
Adding a dependency must be done with care:
* Is the dependency well maintained and adopted in the ecosystem?
* Could we do it without the dependency? If not, why?
* What happens if the dependency is abandoned?
* Document the reason for each dependency, why it has been chosen and why we can't live without it.
Graceful degradation::
The application will connect to various upstream APIs which we can't control.
Should issues arise with one of these APIs, gracefully degrade the feature set and inform accordingly ("This service is currently not available - we're working on it").
Never must the application crash because and upstream API not being reachable, has slow response time or react in an undefined way.
Use database and caches wisely::
External systems like databases, caches or queues add additional complexity and burden to the application operations.
Every additional system must be chosen carefully and the reasoning documented.
Alternatives must be considered and documented.
Business logic vs. views::
Whenever possible, split business logic from views.
This allows to progress the application in the future to allow for different views (For example APIs or other alternative frontends).
Django specifics::
* We use class based views by default, exceptions can be made
* Dynamic configuration happens via environment variables
* Different environments (dev / test / prod) must be clearly separated inside the application
Testing::
Business functionality must be https://docs.djangoproject.com/en/5.1/topics/testing/[tested^] with code.
We preferrably use https://docs.pytest.org/[pytest^].

63
docs/modules/ROOT/pages/web-portal.adoc
View file

@ -1,64 +1,17 @@
= Web Portal
image::web-portal-arch.drawio.svg[]
image::web-portal-arch-current.drawio.svg[]
[TIP]
====
* Production: https://portal.servala.com/[portal.servala.com^]
* Staging: https://staging.portal.servala.com/[staging.portal.servala.com^]
====
The Servala Web Portal is the central multi-tenant multi-service-provider aggregation and self-service main entrypoint for Servala.
Servala is the brand for the product formerly known as "VSHN Application Marketplace".
It offers self-service provisioning, multi-tenancy via organizations, access control, and provides central management access over multi cloud providers and the instances running this way.
The portal is a web application consuming various third party APIs to provide an aggregated and opinionated view.
External resources to read about it:
* http://vshn.ch/marketplace[vshn.ch Website^]
* https://products.vshn.ch/marketplace/index.html[VSHN products site^]
The source code can be found on the https://servala.app.codey.ch/servala/servala-portal[Servala Codey instance^].
== Technology Stack
We choose:
* Python https://docs.djangoproject.com/en/dev/internals/release-process/#term-Long-term-support-release[Django LTS^]
* PostgreSQL as database backend
* https://gunicorn.org/[Gunicorn^] Python WSGI HTTP Server
* https://caddyserver.com/[Caddy^] for serving static files and WSGI, or https://whitenoise.readthedocs.io/en/latest/[WhiteNoise^] (TBD)
* https://docs.astral.sh/uv/[Astral uv^] for Python project, dependency and build management
* https://htmx.org/[htmx] for the dynamic part in the frontend
* https://getbootstrap.com/[Bootstrap 5] for styling the frontend
A complete reasoning for this stack is available in https://vshnwiki.atlassian.net/wiki/spaces/VSHNPM/pages/402718747/Self-Service+Marketplace+Web+Application[our wiki^] (internal page).
== Development Paradigms
Keep usage of third-party dependencies low::
Every external dependency adds a burden on the maintenance of the application.
Adding a dependency must be done with care:
* Is the dependency well maintained and adopted in the ecosystem?
* Could we do it without the dependency? If not, why?
* What happens if the dependency is abandoned?
* Document the reason for each dependency, why it has been chosen and why we can't live without it.
Graceful degradation::
The application will connect to various upstream APIs which we can't control.
Should issues arise with one of these APIs, gracefully degrade the feature set and inform accordingly ("This service is currently not available - we're working on it").
Never must the application crash because and upstream API not being reachable, has slow response time or react in an undefined way.
Use database and caches wisely::
External systems like databases, caches or queues add additional complexity and burden to the application operations.
Every additional system must be chosen carefully and the reasoning documented.
Alternatives must be considered and documented.
Business logic vs. views::
Whenever possible, split business logic from views.
This allows to progress the application in the future to allow for different views (For example APIs or other alternative frontends).
Django specifics::
* We use class based views by default, exceptions can be made
* Dynamic configuration happens via environment variables
* Different environments (dev / test / prod) must be clearly separated inside the application
Testing::
Business functionality must be https://docs.djangoproject.com/en/5.1/topics/testing/[tested^] with code.
We preferrably use https://docs.pytest.org/[pytest^].
The source code can be found on the https://servala.app.codey.ch/servala/servala-portal[Servala Codey instance^].