Skip to content
This repository was archived by the owner on Aug 2, 2025. It is now read-only.

v2.0.1

Pre-release
Pre-release

Choose a tag to compare

View all tags
@Its4Nik Its4Nik released this 03 Jan 15:49
· 276 commits to dev since this release
v2.0.1
b27369f
This commit was created on GitHub.com and signed with GitHub’s verified signature.
GPG key ID: B5690EEEBB952194
Verified
Learn about vigilant mode.

DockStat

v2.0.1

v2 brings some major changes, like project structure, a complete re-write of v1, ...

All new routes! ### Summary is a bit screwed up please see the first link at the top for a better overview of all routes

https://outline.itsnik.de/s/dockstat/doc/api-reference-1PTxqx1MQ6

Available root-routes:

Root-Routes Functionality
/auth Controlling of authentication service
/data Database queries, used for historic data and database management
/frontend Exposed routes for configuring various settings for a/the frontend
/api Only get endpoints, used for fetching configuration data and forcing a new request to the docker sockets instead of querying the database.
/conf Endpoints for configuring backend options
/notification-service configuration of the notification service integrated into the DockStatApi.
/ha Only used for the High Availability synchro

Symbol legend

✅ Required
❌ Optional
⛔ Not needed

Auth routes:

POST: /auth/enable

:::info
sets a current password and enables auth for all endpoints, except the api-docs

:::

Parameter type Parameter name Required?
Query password ✅

POST: /auth/disable

:::info
Disables authentication for all endpoints

:::

Parameter type Parameter name Required?
Query password ✅

Database queries

GET: /data/latest

:::info
Queries the latest entry of the database and provides it as a JSON response.

:::

Parameter type Parameter name Required?
None None ⛔

GET: /data/time/24h

:::info
Queries all the latest data of the database in a 24h timeframe and organizes them in a JSON array.

:::

Parameter type Parameter name Required?
None None ⛔

DELETE: /data/clear

:::info
Clears ***ALL ***entries of the SQLite database.

:::

Parameter type Parameter name Required?
None None ⛔

Frontend routes:

:::info
*) When referring to a config the frontend config at the path: /data/frontendConfiguration.json is meant.

:::

POST: /frontend/show/{==containerName==}

:::info
Sets a container to visible in the config*****

:::

Parameter Type Parameter name Required?
Path ==containerName== ✅

POST: /frontend/tag/{==containerName==/{==tag==}

:::info
Adds a tag to a container inside the config*, as an array for multiple tags

:::

Parameter type Parameter name Required?
Path ==containerName== ✅
Path ==tag== ✅

POST: /frontend/pin/{==containerName==}

:::info

Sets “pinned” to true, inside the config*

:::

Parameter type Parameter name Required?
Path ==containerName== ✅

POST: /frontend/add-link/{==containerName==}/{==link==}

:::info
Sets the “link” string inside the config*

:::

Parameter type Parameter name Required?
Path ==containerName== ✅
Path (might change) ==link== ✅

POST: /frontend/add-icon/{==containerName==}/{==icon==}/{==useCustomIcon==}

:::info
Configures the icon string inside the config, when useCustomIcon is true the path file path of the icon gets to adjust with custom/{==icon==}.png

:::

Parameter type Parameter name Required?
Path ==containerName== ✅
Path (string WITHOUT file type) ==icon== ✅
Path (boolean) ==useCustomicon== ❌

DELETE: /frontend/hide/{==containerName==}

:::info
Sets “hidden” to true inside the config*

:::

Parameter type Parameter name Required?
Path ==containerName== ✅

DELETE: /frontend/remove-tag/{==containerName==}/{==tag==}

:::info
Removes the specified tag from the frontend config* tag-array

:::

Parameter type Parameter name Required?
Path ==containerName== ✅
Path ==tag== ✅

DELETE: /frontend/unpin/{==containerName==}

:::info
Sets “pinned” to false inside the config*

:::

Parameter type Parameter name Required?
Path ==containerName== ✅

DELETE: /frontend/remove-link/{==containerName==}

:::info
Removes the “link” string from the config*

:::

Parameter type Parameter name Required?
Path ==cotnainerName== ✅

DELETE: /frontend/remove-icon/{==containerName==}

:::info
Removes the “icon” string from the config*

:::

Parameter type Parameter name Required?
Path ==containerName== ✅

API

GET: /api/hosts

:::info
Retrieves a JSON list of all available hosts

:::

Parameter type Parameter name Required?
None None ⛔

GET: /api/host/{==hostName==}/stats

:::info
Queries a specified host and provides data as a JSON structure

:::

Example response:

{
  "hostName": "XXX",
  "info": {
    "ID": "XXX",
    "Containers": 19,
    "ContainersRunning": 19,
    "ContainersPaused": 0,
    "ContainersStopped": 0,
    "Images": 17,
    "OperatingSystem": "Ubuntu 22.04.5 LTS",
    "KernelVersion": "5.15.0-121-generic",
    "Architecture": "x86_64",
    "MemTotal": 8123764736,
    "NCPU": 4
  },
  "version": {
    "Components": {
      "Engine": "27.3.1",
      "containerd": "1.7.22",
      "runc": "1.1.14",
      "docker-init": "0.19.0"
    }
  }
}
Parameter type Parameter name Required?
Path ==hostName== ✅

GET: /api/containers

:::info
Queries all docker hosts directly and provides a JSON output

:::

Example response:

{
  "XXX": [
    {
      "name": "portainer",
      "id": "XXX",
      "hostName": "XXX",
      "state": "running",
      "cpu_usage": 1670000,
      "mem_usage": 10727424,
      "mem_limit": 8123764736,
      "net_rx": 584519242,
      "net_tx": 27036706,
      "current_net_rx": 584519242,
      "current_net_tx": 27036706,
      "networkMode": "docker-important_default"
    }
   ],
   "YYY": [
    {
      "name": "dozzle",
      "id": "XXX",
      "hostName": "YYY",
      "state": "running",
      "cpu_usage": 1670000,
      "mem_usage": 10727424,
      "mem_limit": 8123764736,
      "net_rx": 584519242,
      "net_tx": 27036706,
      "current_net_rx": 584519242,
      "current_net_tx": 27036706,
      "networkMode": "default"
    }
   ]
  }
Parameter type Parameter name Required?
None None ⛔

GET: /api/config

:::info
Provides the current backend config as JSON

:::

Example response:

{
  "hosts": [
    {
      "name": "XXX",
      "url": "YYY",
      "port": "ZZZ"
    }
  ]
}
Parameter type Parameter name Required?
None None ⛔

GET: /api/current-shedule

:::info
Retrieves and provides the current schedule settings in seconds

:::

Example response:

{
  "interval": 300
}
Parameter type Parameter name Required?
None None ⛔

GET: /api/frontend-config

:::info
Provides the frontend config used for various settings

:::

Example response:

[
  {
    "name": "XXX",
    "hidden": true,
    "tags": [
      "YYY"
    ],
    "pinned": true
  }
]
Parameter type Parameter name Required?
None None ⛔

GET: /api/status

:::info
Returns a 200 status with an "up" message to indicate the server is up and running. Used for Health checks

:::

Example response:

{
  "status": "up"
}
Parameter type Parameter name Required?
None None ⛔

PUT: /conf/addHost

:::info
Adds another host as target

:::

Response Code Description
200 Host added successfully.
400 Bad request, invalid input.
500 An error occurred while adding the host.
Parameter type Parameter name Required?
Query name ✅
Query URL ✅
Query port ✅

Conf

PUT: /conf/scheduler

:::info
Set a new scheduler interval (has to be 5 minutes or more)

:::

Response code Description
200 Fetch interval set successfully.
400 Invalid interval format or out of range.
Parameter type Parameter name Required?
Query interval ✅

DELETE: /conf/removeHost

:::info
Removes a specified host from the config

:::

Response code Description
200 Host removed successfully.
404 Host not found.
500 An error occurred while removing the host.
Parameter type Parameter name Required?
Query hostName ✅

Notification Services

GET: /notification-service/get-template

:::info
Retrieve the notification template

:::

Example response:

{
  "message": "{{name}} is {{state}}"
}
Parameter type Parameter name Required?
None None ⛔

POST: /notification-service/set-template

:::info
Update the notification text with templating functionality

:::

Example Request body:

{
  "message": "string"
}
Parameter type Parameter name Required?
Request body None ✅

POST: /notification-service/test/{==type==}/{==containerId==}

:::info
Send a test notification using an existing container as a data source for the template

:::

might change in the future to use a standart test message

Parameter type Parameter name Required?
Path ==type==* ✅
Path ==containerId== ✅

Type*: this is the notification service you are trying to test, for example: telegram, mail, pushbullet, …

New features:

  • more npm run scripts
  • now TypeScript based
  • better project structuring see project structure
  • way, way, more endpoints for gathering the statistics
  • improved logging
  • integrated sync for high availability

Please see #20 for a more in depth look at current development

new npm run scripts

Lifecycle scripts included in dockstatapi@2.0.1:
  start
    npm run local-env-file && tsx src/server.ts
  local-env-file
    bash ./src/misc/createEnvDev.sh
  dev
    npm run local-env-file && nodemon
  dev:trace
    npm run local-env-file && nodemon --trace-uncaught --trace-warnings
  dep
    bash ./src/misc/dependencyGraphs/createDependencyGraph.sh
  dep:remove
    bash ./src/misc/removeUnusedDeps.sh && npm run dep
  build
    npx tsc
  build:mini
    npx tsc && bash ./src/misc/minifyDist.sh --build-only
  build:docker
    docker build . -t "dockstatapi:local" -f ./docker/Dockerfile-dev
  mini
    bash ./src/misc/minifyDist.sh
  docker
    docker compose -f docker/docker-compose.yaml up -d && bash ./src/misc/.tmux.sh; docker compose -f docker/docker-compose.yaml down
  docker:build
    npm run build:docker && npm run docker
  prettier
    npx prettier -c ./src/**/*.ts --parser typescript --write && npx prettier -c ./.github/workflows/*.yaml --parser yaml --write && npx prettier -c ./**/*.md --parser markdown --write && npx prettier -c ./**/*.json --parser json --write
  lint
    npx eslint
  lint:fix
    npx eslint --fix
  license
    bash ./src/misc/credits.sh
  finish
    npm run local-env-file && npm run license && npm run prettier && npm run lint

GitHub's auto generated stuff:

What's Changed

  • Fix file names by @Its4Nik in #1
  • Its4 nik patch 1 by @Its4Nik in #2
  • Bump the npm_and_yarn group across 1 directory with 2 updates by @dependabot in #7
  • Bump the npm_and_yarn group across 1 directory with 2 updates by @dependabot in #6
  • Bump the npm_and_yarn group across 1 directory with 2 updates by @dependabot in #4
  • Bump the npm_and_yarn group across 1 directory with 2 updates by @dependabot in #3
  • Dev - Healthcheck by @Its4Nik in #8
  • Dev - Drastically improve container info gathering by @Its4Nik in #9
  • Dev - Notifications are here! by @Its4Nik in #10
  • Update notify.sh (#11) by @Its4Nik in #12
  • Fix code scanning alert #1: Missing rate limiting by @Its4Nik in #14
  • Update notify.sh (#11) by @Its4Nik in #15
  • Refactor - Breaking Changes for current DockStat frontend by @Its4Nik in #18
  • Switch to ES6 and TypeScript by @Its4Nik in #21

New Contributors

Full Changelog: V1...v2.0.1

Contributors

dependabot and Its4Nik
Assets 2
Loading