Skip to content

Serves the API and contains the application logic

License

Notifications You must be signed in to change notification settings

envelope-zero/backend

Repository files navigation

Envelope Zero backend

Release Go Reference Go Report Card

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

See docs/upgrading.md.

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.