Skip to content
OpenShockPublic

About

Backend for the OpenShock solution, that enables controlling shock collars over the internet.

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

28 stars

Watchers

1 watching

Forks

Latest commit

 

History

1,596 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

OpenShock API

Documentation GitHub license GitHub Sponsors Discord

master Build Status CodeQL Status
develop Build Status CodeQL Status

API Documentation

You can access our Open API Doc here:

https://api.openshock.app/scalar/viewer

Configuration

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.

Turnstile

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

EMail

MAILJET

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

SMTP

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

security.txt

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).

(Live Control) Gateway

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

Deployment / Self Hosting

The OpenShock stack consists of the following components:

  • Postgres 18+ as database, with the TimescaleDB extension in its Community edition (the Apache-2 only -oss builds lack features the schema needs). It has to be in shared_preload_libraries, the API refuses to start otherwise. The db service in docker-compose.yml uses such an image built on top of postgres:18 (ghcr.io/openshock/postgres-timescaledb), so an existing postgres:18 data 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

Requirements

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

Using Docker (provided docker-compose.yml)

  1. Grab the docker-compose.yml and .env file from the repository
  2. Change the values in the .env file
  3. 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.

Upgrading to TimescaleDB

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

  1. Install the TimescaleDB Community edition for your Postgres version (e.g. the timescaledb-2-postgresql-18 package from Timescale's repository). The -oss builds and managed offerings that only ship the Apache-2 edition do not work.
  2. Add timescaledb to shared_preload_libraries in postgresql.conf and restart Postgres.
  3. 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.

Security

Found a security vulnerability? Please do not open a public issue. Report it privately as described in SECURITY.md.

Contributing

See CONTRIBUTING.md. Everyone taking part in the project is expected to follow our Code of Conduct.

Support development!

You can support the OpenShock Dev Team here: Sponsor OpenShock

About

Backend for the OpenShock solution, that enables controlling shock collars over the internet.

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

28 stars

Watchers

1 watching

Forks

Releases

Packages

Used by

Contributors

Languages