Skip to main content

API Development

The files for the API server component of Thermostat are located in the api folder in the repository. The API server is a Node.js application that serves the SSH and HTTP components of the Thermostat API. Please be sure you understand the Thermostat API Architecture before attempting to make changes to this system.

You can run development commands on the API server by using the thermostat run api command to run the Yarn scripts defined in api/package.json. You can also use the thermostat run api_cli command to run special CLI commands that are only accessible on the server side of Thermostat, you can see the list of CLI commands the server supports in api/src/cli.ts.

Environment Variables​

You need to set the following variables in the api/.env file in order to run the Thermostat CLI:

  • GITLAB_ACCESS_TOKEN: This should be a GitLab Access Token that is able modify the repositories in the Fahrenheit GitLab group.
  • GITLAB_DEPLOY_TOKEN_USERNAME: This should be the username of a GitLab Deploy Token that has access to read the Thermostat GitLab repository.
  • GITLAB_DEPLOY_TOKEN_PASSWORD: This should be the password of the GitLab Deploy token described in the environment variable above.
  • SSH_HOST_KEY: This should be a base64-encoded host key that is used to encrypt connections for the SSH API.
  • DB_HOST: This should be the hostname of the Postgres server used by this application, it should generally be thermostat_api_postgres.
  • DB_PORT: This should be the port of the Postgres server used by this application, it should generally be 5432.
  • DB_USERNAME: This should be the username of the user that is used to connect to the Postgres server used by this application, it should generally be postgres.
  • DB_PASSWORD: This should be the password of the user that is used to connect to the Postgres server used by this application.
  • DIGITALOCEAN_API_KEY: This should be a DigitalOcean Personal Access Key that has access to the Fahrenheit DigitalOcean team.

Code Files​

This is a brief overview of the purposes of all the important code files in the API codebase:

  • api/package.json: This file contains scripts and dependencies used for API server development.
  • api/webpack.config.js: This file contains the build configuration for the API server application.
  • api/config/docker/Dockerfile: This is the Docker image definition file for the API server application Docker container.
  • api/static/entrypoint: This is the entrypoint script for the API server application Docker container.
  • api/config/docker/docker-compose.yml: This is the template for the Docker compose file that is used to run the API server application and the supporting systems like the PostgreSQL database server.
  • api/.env: This file contains environment variables needed for running the CLI application.
  • api/ormconfig.ts: This file is the TypeORM configuration file.
  • api/src/entities: This folder contains the TypeORM entity files.
  • api/src/migrations: This folder contains the TypeORM migration files.
  • api/src/templates/serverinit.sh: This file is a utility script that can be used for initializing a new Linux server for use with Thermostat. We use this for initializing most of our DigitalOcean servers.
  • api/src/templates/employeeserverinit.sh: This file is a utility script that can be used for initializing a new Linux server for an employee to use with Thermostat. We use this for initializing most of our employee DigitalOcean servers.
  • api/src/templates/install.sh: This file is the Thermostat CLI installation script.
  • api/src/index.ts: This file is the main entrypoint of the API server application, it loads the configuration and serves the SSH and HTTP APIs.
  • api/src/cli.ts: This file is the entrypoint for the API server CLI commands that can be run using the thermostat run api_cli command.
  • api/src/ssh.ts: This file contains the code for serving the SSH API.
  • api/src/http.ts: This file contains the code for serving the HTTP API.
  • api/src/utils/logging.ts: This file contains utility functions for handling logging.
  • api/src/utils/database.ts: This file contains utility functions for interfacing with the Postgres database.
  • api/src/utils/digitalocean.ts: This file contains utility functions for interfacing with the DigitalOcean API.
  • api/src/utils/gitlab.ts: This file contains utility functions for interfacing with the GitLab API.
  • api/src/utils/general.ts: This file contains generic utility functions that are not Thermostat-specific.