| master | ||
| develop |
You can access our Open API Doc here:
https://api.openshock.app/scalar/viewer
The API can be configured using the following environment variables. These variables should be available to all containers in the stack. Preferred way is a .env file.
| Variable | Required | Default value | Allowed / Example value |
|---|---|---|---|
OPENSHOCK__DB__CONN |
x | Host=postgres-server-host;Port=5432;Database=openshock;Username=openshock;Password=superSecurePassword |
|
OPENSHOCK__DB__SKIPMIGRATION |
false |
true, false |
|
OPENSHOCK__DB__DEBUG |
false |
true, false |
|
OPENSHOCK__ACCOUNT__REGISTRATIONENABLED |
true |
true, false - false disables new user sign-ups |
|
OPENSHOCK__FRONTEND__BASEURL |
x | https://my-openshock-instance.net or https://shocklink.net |
|
OPENSHOCK__FRONTEND__SHORTURL |
x | https://myoi.net or https://shockl.ink |
|
OPENSHOCK__FRONTEND__COOKIEDOMAIN |
x | my-openshock-instance.net |
|
OPENSHOCK__REDIS__CONN |
x | redis-server-host:6379 |
|
OPENSHOCK__MAIL__SENDER__EMAIL |
x | system@my-openshock-instance.net |
|
OPENSHOCK__MAIL__SENDER__NAME |
x | MyOpenShockInstance System |
|
OPENSHOCK__MAIL__TYPE |
x | MAILJET, SMTP |
|
OPENSHOCK__TURNSTILE__ENABLE |
x | true, false |
Refer to the Npgsql Connection String documentation page
for details about OPENSHOCK__DB_CONN.
Refer to StackExchange.Redis Configuration
documentation page for details about OPENSHOCK__REDIS__CONN.
When Turnstile enable is set to true, the following environment variable is required:
| Variable | Required | Default value | Allowed / Example value |
|---|---|---|---|
OPENSHOCK__TURNSTILE__SITEKEY |
x | ||
OPENSHOCK__TURNSTILE__SECRETKEY |
x |
You need these environment variables to use Mailjet:
| Variable | Required | Default value | Allowed / Example value |
|---|---|---|---|
OPENSHOCK__MAIL__MAILJET__KEY |
x | ||
OPENSHOCK__MAIL__MAILJET__SECRET |
x |
You need these environment variables to use SMTP:
| Variable | Required | Default value | Allowed / Example value |
|---|---|---|---|
OPENSHOCK__MAIL__SMTP__HOST |
x | mail.my-openshock-instance.net |
|
OPENSHOCK__MAIL__SMTP__PORT |
587 |
587 |
|
OPENSHOCK__MAIL__SMTP__USERNAME |
x | system@my-openshock-instance.net |
|
OPENSHOCK__MAIL__SMTP__PASSWORD |
x | superSecurePassword |
|
OPENSHOCK__MAIL__SMTP__ENABLESSL |
true |
true or false |
|
OPENSHOCK__MAIL__SMTP__VERIFYCERTIFICATE |
true |
true or false |
The API, gateway and cron containers can publish a security.txt file (RFC 9116) at
/.well-known/security.txt, telling security researchers where to report a vulnerability in your instance.
It is disabled until a contact is configured. Do not put OpenShock's contact details here for an instance OpenShock
does not operate.
| Variable | Required | Default value | Allowed / Example value |
|---|---|---|---|
OPENSHOCK__SECURITYTXT__CONTACT |
Comma separated mailto: or https: URIs, e.g. mailto:security@my-openshock-instance.net |
||
OPENSHOCK__SECURITYTXT__EXPIRES |
x (if contact is set) | 2027-10-31T00:00:00Z - should be less than a year ahead |
|
OPENSHOCK__SECURITYTXT__POLICY |
https://my-openshock-instance.net/security-policy |
||
OPENSHOCK__SECURITYTXT__ACKNOWLEDGMENTS |
https://my-openshock-instance.net/security-thanks |
||
OPENSHOCK__SECURITYTXT__PREFERREDLANGUAGES |
en, de |
Once the Expires date has passed the file is no longer served (and a warning is logged at startup), so renew the
date before it runs out. A security.txt only covers the exact host it is served from, and only from the root of
that host: when the API is mounted under a path prefix, serve the file from whatever answers at the root instead
(usually the frontend).
These are the environment variables for the live control gateway. They are only required on the gateway container and are configuration local to the gateway.
| Variable | Required | Default value | Allowed / Example value |
|---|---|---|---|
OPENSHOCK__LCG__FQDN |
x | de1-gateway.my-openshock-instance.net de1-gateway.shocklink.net |
|
OPENSHOCK__LCG__COUNTRYCODE |
x | DE or XX as a placeholder / unknown |
The OpenShock stack consists of the following components:
- Postgres 18+ as database, with the TimescaleDB extension in its
Community edition (the Apache-2 only
-ossbuilds lack features the schema needs). It has to be inshared_preload_libraries, the API refuses to start otherwise. Thedbservice indocker-compose.ymluses such an image built on top ofpostgres:18(ghcr.io/openshock/postgres-timescaledb), so an existingpostgres:18data directory can be reused as is. - Redis-Stack (with keyspace events KEA) (preferably DragonflyDB)
- One or multiple APIs (container, API)
- One or multiple gateways (container, LCG)
- One or multiple cron daemons (container, CRON)
- Frontend - stateless, can run on edge
OpenShock instance needs to be under the same domain name to work correctly. This is due to cookie limitations in browsers.
Frontend: https://openshock.app
API: https://api.openshock.app
LCG: https://de1-gateway.openshock.app
In this case your cookie domain would be openshock.app, even if the frontend would be hosted under e.g. https://frontend.openshock.app
- Grab the
docker-compose.ymland.envfile from the repository - Change the values in the
.envfile - Adjust traefik to your needs (e.g. add SSL certificates)
Run with docker compose up -d
You could also bring your own reverse proxy.
You would need to remove traefik from the docker-compose.yml and route the traffic in your reverse proxy.
Control logs are stored in a TimescaleDB hypertable. When upgrading an existing instance:
With the provided docker-compose.yml: pull the new compose file and run docker compose up -d. The db service
now uses ghcr.io/openshock/postgres-timescaledb, which is postgres:18 with TimescaleDB on top, so your existing
postgres-data directory is reused and the API migrates it on startup.
With your own Postgres: before upgrading OpenShock
- Install the TimescaleDB Community edition for your Postgres version (e.g. the
timescaledb-2-postgresql-18package from Timescale's repository). The-ossbuilds and managed offerings that only ship the Apache-2 edition do not work. - Add
timescaledbtoshared_preload_librariesinpostgresql.confand restart Postgres. - Make sure the database user OpenShock connects with may run
CREATE EXTENSION timescaledb(usually a superuser), or create the extension in the OpenShock database yourself.
The API checks this on startup and refuses to migrate otherwise. Existing control logs are converted in place, from then on they are kept for a year by a retention policy.
Found a security vulnerability? Please do not open a public issue. Report it privately as described in SECURITY.md.
See CONTRIBUTING.md. Everyone taking part in the project is expected to follow our Code of Conduct.
You can support the OpenShock Dev Team here: Sponsor OpenShock