You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
Jonas Lochmann 24877ba44e
Add docker compose file which includes the database
1 week ago
other Initial commit 1 year ago
scripts Remove sign in with Google account 8 months ago
src Make the ping interval configurable 1 month ago
.gitignore Initial commit 1 year ago
Dockerfile Initial commit 1 year ago
LICENSE Initial commit 1 year ago Add docker compose file which includes the database 1 week ago
package-lock.json Update dependencies 2 weeks ago
package.json Update dependencies 2 weeks ago
tsconfig.json Initial commit 1 year ago
tslint.json Initial commit 1 year ago


This is the server for the connected mode in TimeLimit.


This application only supports running a single instance of it. When clustering, push messages do not work anymore between devices connected to different devices and the rate limiting is per instance.


Option 1: Build (run sudo docker build -t timelimit-server . in this directory) and use a docker image
Option 2: Install Node.JS (see below for detailed usage)

To test it, open http://server/time, it should show a timestamp


npm start

This runs all pending migrations and starts the server.

npm run build

This “compiles” the application.

npm run lint:fix

This fixes the causes of lint warnings (where possible).

Configuration (environment variables)

    • this specifies the database to use
    • default value: sqlite://test.db (sqlite database in the source code directory)
    • supports mysql, postgresql and sqlite (sqlite in development builds only because it's declared as dev dependency)
    • looks like postgres://
    • no extra setup needed
      • when starting the application, the database tables are created/ migrated
        • this only works for upgrading; if you intend to eventually downgrade, make a backup first (you should make backups in all cases before an upgrade)
  • PORT
    • the port at which the server should listen
    • should be set to production in production
    • when using development, then mails are not sent; instead they are written to a html file which is opened
    • key for validating purchases
    • purchases using google play don't work without it
    • sender (for the from-field) for sent mails
    • a string which is added to the footer of the sent mails
    • default value: not defined
    • a password which allows to use some APIs
    • admin APIs are disabled when this is not set
    • list of domains, separated by comma
    • if the user tries to use such a mail service, then he will get the notification that this provider is not supported
    • list of mail addresses ( or domains (, separated by comma
    • if a user requests signing in with a mail address which is not in this list, then the request is rejected
    • if the list is empty, then any mail address (except with domains from the blacklist) is allowed
    • note: this allows a third party who knows the server url to check if a certain mail address is allowed by trying to sign in with it
    • yes or no (default: no)
    • disables creating new families if yes is selected
    • ping interval at the websocket in seconds


This server application itself does not support HTTPS. You have to use an other tool to use HTTPS. One options for this is to use nginx with the following site config:

# don't forget to update the port for your local configuration
# the max_fails is important - otherwise nginx
# marks the server sometimes as unreachable if it is restarted
# or starts after nginx
upstream timelimitbackend {
  server localhost:8080 max_fails=0;

server {
  listen 443 ssl;
  listen [::]:443 ssl;

  # don't forget to update the domain
  server_name my.domain;

  # don't forget to update the paths
  ssl_certificate /my/fullchain.pem;
  ssl_certificate_key /my/privkey.pem;

  # eventually configure the SSL parameters here

  location / {
    proxy_pass http://timelimitbackend/;

    client_max_body_size 10m;
    # the following is required for websocket support
    # without websockets, the client will not detect
    # that there is a connection and it will not sync
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_http_version 1.1;

Admin API

When the ADMIN_TOKEN environment variable was set, then there is a admin API available at http(s)://server/admin. It can be used by the TimeLimit Server Admin UI.


To enable the automated purchase feature, set the GOOGLE_PLAY_PUBLIC_KEY environment variable. The value for the official builds which are distributed using the Play Store can be found at

Additionally, there is the admin API which allows one to unlock the premium features.

example docker-compose.yml with included database

(don't forget to build the docker image first)

version: '3'
    image: 'timelimit-server:latest'
      NODE_ENV: production
      DATABASE_URL: mariadb://timelimit:timelimitpassword@database:3306/timelimit
      PORT: 8080
      # put additional config variables here
     - "8080:8080"
    restart: always
    # you should enable logging/ comment this out during testing
    #  driver: none
    - database
    image: 'mariadb:10'
      MYSQL_ROOT_PASSWORD: rootpassword
      MYSQL_DATABASE: timelimit
      MYSQL_USER: timelimit
      MYSQL_PASSWORD: timelimitpassword
     - ./database:/var/lib/mysql

The database files will be saved at the folder which contains the docker-compose.yml. You should change the passwords.

Docker starts both (TimeLimit and the database) at the same time, so the TimeLimit server will crash a few times due to the missing database before it starts working.

example docker-compose.yml with external databases

(don't forget to build the docker image first)

version: '2'
    image: 'timelimit-server:latest'
      NODE_ENV: production
      DATABASE_URL: postgres://
      PORT: 8080
      # put additional config variables here
    restart: always
    # you should enable logging during testing
      driver: none
    # easy solution to use a database which does not run within docker
    network_mode: "host"
    # otherwise:
    # redirect host port 9000 to guest port 8080 (to allow access to the API)
    # ports:
    #  - "9000:8080"
    # in case the database runs outside of docker and you don't want to use the host network mode, see