Envelope Zero backend

Check out the documentation at envelope-zero.org!

Features

For a high level view of planned complex features, check the milestones.

To see all planned features, check the list of issues with the enhancement label.

Usage

Upgrading

Configuration

⚠️ You need to configure a persistent storage to be mounted to /data, e.g. a docker volume. If you do not do this, upon deleting the container, all your data will be lost.

The backend can be configured with the following environment variables.

Name	Type	Default	Description
`API_URL`	`string`	none, must be set	The URL of the API, e.g. `https://ez.example.com/api`
`GIN_MODE`	One of `release`, `debug`	`release`	The mode that gin runs in. Only set this to `debug` on your development environment!
`PORT`	`number`	`8080`	The port the backend listens on
`LOG_FORMAT`	One of `json`, `human`	`json` if `GIN_MODE` is `release`, otherwise `human`	If log output is written human readable or as JSON.
`CORS_ALLOW_ORIGINS`	`string`	`""`	ℹ️ This is only needed for frontend development. Defines hosts that are allowed to use cross origin requests, separated by spaces.
`ENABLE_PPROF`	`bool`	`false`	If set to `true`, pprof profiles for application profiling are made available at `/debug/pprof`. ⚠️ If you do not know what this means, do not turn this on.
`DISABLE_METRICS_LOGS`	`bool`	`false`	Set to `true` to disable logs for the `/metrics` endpoint
`DISABLE_HEALTHZ_LOGS`	`bool`	`false`	Set to `true` to disable logs for the `/healthz` endpoint

Deployment methods

The recommended way for production deployments is to run the backend with the OCI image or a binary directly. For up-to-date binaries, check out the Releases page.

If you want to deploy with a method not listed here, you are welcome to open a discussion to ask any questions needed so that this documentation can be improved.

On Kubernetes

You can run the backend on any Kubernetes cluster with a supported version using the morremeyer/generic helm chart with the following values:

image:
  repository: ghcr.io/envelope-zero/backend
  tag: v4.1.0

# All data is stored to a sqlite database in /data.
# Make sure to persist and backup this directory.
persistence:
  enabled: true
  mountPath: /data

podSecurityContext:
  fsGroup: 65532

affinity:
  podAffinity:
    requiredDuringSchedulingIgnoredDuringExecution:
      - labelSelector:
          matchLabels:
            app.kubernetes.io/instance: ez-backend # Replace this with the name of your helm release
            app.kubernetes.io/name: generic
        topologyKey: "kubernetes.io/hostname"

ports:
  - name: http
    containerPort: 8080
    protocol: TCP

ingress:
  enabled: true
  hosts:
    - host: envelope-zero.example.com
      paths:
        - path: /api
  tls:
    - hosts:
        - envelope-zero.example.com

livenessProbe:
  httpGet:
    path: /healthz

readinessProbe:
  httpGet:
    path: /healthz
    port: http

Supported Versions

As the backend is constantly developed, only the latest minor version is supported (versions are MAJOR.MINOR.PATCH). If you encounter an issue, please update to the latest version of the backend and verify that it still exists in that version.

Please check the releases page for the latest release.

Contributing

Please see the contribution guidelines.

Versioning

This project is versioned using Semantic Versioning 2.0.0.

The public API is defined as:

The API endpoints, meaning the routes, parameters, HTTP response codes, and request and response body format
The behavior of the API endpoints no matter the signature of the endpoint is.

Not part of the public API is:

The go module itself, meaning that exported function signatures or behaviors can change at any point in time
The exact error messages. All error messages are intended to be displayed to users and can change with every release to improve them.