Troubleshooting
When I try to run a Thermostat command I get an error message like "Unable to connect to Thermostat API. Please ensure that your SSH agent is running,that your SSH server allows socket forwarding, and that your SSH key is present in Thermostat."
First, do what the error message says and double check that your SSH agent is running, that your SSH server allows socket forwarding, and that your SSH key is present in Thermostat. You can check that your SSH agent is running and has your key loaded by running ssh-add -l, it should output something like 2048 SHA256:gejFo348jsdElk3m4fSDAFw6Mwl132FmepapfelFe6l /home/user/.ssh/id_rsa (RSA) indicating that your private key is loaded. You can check that your SSH server allows socket forwarding by checking your OpenSSH server configuration file which is usually located at /etc/ssh/sshd_config, refer to the OpenSSH documentation on configuring this. You can check that your SSH key is present in Thermostat by checking your employee/server user record in the Thermostat database (see here for more details) to ensure it has the correct public key that is associated with the private key loaded into your SSH agent. If all of these things seem correct, it may be a problem in the Thermostat API server itself, so follow the Thermostat API server troubleshooting guide here.
My Thermostat application deployed successfully but I'm getting a 404 in my browser when trying to view it, what do I do?
There are many reasons why this might happen, but some common things to look for are:
- Double check that the Nginx configuration is working as expected. You can look at the actual Nginx configuration that Thermostat is using by looking in the
/var/lib/thermostat/services/nginx/configfolder. Double check that you are using the correct domain name for the website just as it is listed in the actual Nginx configuration. Also be sure that the root folder specified in the Nginx configuration is pointing to the correct path where the public web files are stored in the code folder. - Double check that the application folder is correctly bind-mounted into the service Docker containers. Thermostat uses bind-mounts to mount the application code and data folders into the Thermostat service containers, and sometimes Docker can be flaky about how it handles these mounts. You should use docker exec to look inside the Thermostat service containers in the
/data/apps/folder to make sure the application code and data appears to be mounted correctly in the containers.
When I run Thermostat commands I see the message "WARNING! Application path "/path/to/application" does not exist on host! Unable to create application bind mount!"
This error happens when you delete the folder for a deployed Thermostat application without removing it from Thermostat first. You must always remember to run thermostat remove before deleting an application's files. In order to fix this you must re-create the folder that the application was deployed in and re-create the code folder for the application, restart Thermostat with docker restart thermostat to reset the application bind mounts, and then run the thermostat remove command in that folder. Note that the code folder must contain a valid Git repository that contains a valid Thermostat configuration file so the easiest way to re-create the code folder is by re-cloning it manually using git clone <git repo url> code.
When I try to run a Thermostat command I get an error message like "Unable to acquire application lock: Lock file is already being held"
Thermostat uses lock files to prevent multiple Thermostat processes from accessing the same files at once. If you get an error like this it means there's already some other Thermostat process locking the files you're trying to access. Thermostat runs exclusively in Docker, so you can look at your docker containers with docker ps -a to see what existing Thermostat commands are running. It's common for there to be lingering Thermostat command containers running in Docker if you do not properly close a Thermostat command you are running with Ctrl+C before exiting your terminal, you will need to manually remove these containers if you have them using docker rm.
When I try to run a Thermostat command I get an error message like "thermostat: No such file or directory"
Thermostat installs the thermostat Bash script that is used for running Thermostat commands to /usr/local/bin/thermostat. Therefore the /usr/local/bin folder needs to be in your PATH environment variable for your shell to be able to execute the thermostat command. Run echo $PATH to check that the /usr/local/bin folder shows up there.
When I try to run a Thermostat command I get an error message like "Got permission denied while trying to connect to the Docker daemon socket at unix:///var/run/docker.sock"
Thermostat runs in Docker, so your Linux user must have permission to access Docker in order for Thermostat to function. This error message indicates that your Linux user does not have permissions to access Docker at all. If you get an error like this when running Thermostat, you would typically also get the same error message when you try to run other Docker commands like docker ps. Different distributions handle Docker permissions differently so you may need to research the proper way to give your user Docker permissions on your machine, but typically on Debian-based systems this is handled via a docker group that you can add your user to by running the command sudo usermod -a -G docker <your user name>. This error can also be caused by your Docker daemon not accepting connections on the typical /var/run/docker.sock sockfile, you will need to check your distribution's Docker daemon configuration to ensure it is configured properly to use this sockfile for connections.
When I try to run a Thermostat command I get an error message like "Unable to establish SSH connection to localhost! Please ensure that you have an SSH server running on port 22."
As the error message indicates, you need to ensure you have a SSH server running that is accepting incoming connections on port 22. Different distributions handle SSH server administration differently, but typically on Debian-based systems you can check if the SSH server is running by running sudo service ssh status. You will also need to check the SSH server configuration in /etc/ssh/sshd_config to ensure it is accepting connections on port 22, the Port configuration value there should be set to 22. The server will also need to accept SSH sessions for the root user account which is sometimes disabled, be sure to check that the PermitRootLogin configuration value is set to yes in the /etc/ssh/sshd_config file to allow root logins. You should also be sure that the AuthorizedKeysFile configuration value is set to .ssh/authorized_keys in /etc/ssh/sshd_config because Thermostat adds its public key to the /root/.ssh/authorized_keys file for authentication, so if the SSH server is looking somewhere else for authorized keys then Thermostat will not be able to connect. On some versions of Ubuntu you also need to add PubkeyAcceptedKeyTypes=+ssh-rsa to the /etc/ssh/sshd_config file in order for Thermostat to work since it uses an RSA public/private key pair for authentication with the local SSH server.
When I try to install Thermostat I get an error message like "Cannot mount volume of type "bind": Bind target "/var/lib/thermostat" does not exist!"
This typically happens because you are using the Snap version of Docker which is unable to bind mount files outside of your home directory properly. This prevents Thermostat from working because it needs to bind the /var/lib/thermostat folder into the Thermostat container which the Snap version of Docker does not support. You must uninstall the Snap version of Docker and install Docker directly using your Linux distribution's package manager, on Debian-based systems this is typically done using sudo apt install docker.io.