Skip to main content

Help! My Server doesn't startup

Puh. We are sorry about that! This is probably the worst case scenario, and one of the hardest to debug. But don't worry, we will get you through this.

Before we start​

This troubleshooting section will assume you have read the Getting Started section and have a basic understanding of how Arkitekt works. This section will also assume that you are using Konstruktor to start your server. If you are using the docker compose setup, we would kindly ask you to switch to Konstruktor for the time being, and see if you can get it to work there. It will make it easier for us to help you.

Please open an Issue on GitHub

No matter if you find an easy solution to your problem, if you have the time, please open an Issue on our GitHub and explain your problem, especially if you think it's a bug. Every general feedback and improvement notes are always welcome there.

Lets start with the basics. Where did you get stuck? We will guide you through a few checkpoints.

Step Zero: The basics

Step One: Konstruktor

Step Three: The Deployment

Step Four: The Access

The basics​

Docker Installation​

Installing Docker has recently become way more straightforward and easy. If you are using Windows or Mac, you can simply download the installer from the Docker Website. If you are using Linux, you can follow the instructions for your distribution here.

Docker on Windows​

Installing of Docker on Windows has become way easier recently. But it's still the trickiest of all operation systems. And it's not always clear what the problem is. So let's try to figure out what's going on. First things first:

  • You need to have Administrator rights on your computer. If you are using a university computer, you might need to ask your IT department to install Docker for you.

  • Docker requires Windows 10 and higher, that means you need to have one of the following Windows versions installed:

    • Windows 11 64-bit: Home or Pro version 21H2 or higher, or Enterprise or Education version 21H2 or higher.
    • Windows 10 64-bit: Home or Pro 22H2 (build 19045) or higher, or Enterprise or Education 22H2 (build 19045) or higher.

Docker needs to be able to run a Virtualization layer on your computer. For this it can use either Hyper-V or Windows Subsystem for Linux 2 (WSL2). We strongly recommend using WSL2, as it is much faster and more stable, and has become the default option for docker.

If you are using Windows 10, you can check if you have WSL2 installed by opening a PowerShell and running the following command:

wsl --list --verbose

Otherwise you can follow the instructions here to install WSL2.

Docker on Mac​

Installing Docker on Mac is usually pretty straightforward. If you encounter any problems, it's probably because you are using an older Mac, or something in your system is blocking the installation. Please open an Issue on our GitHub and we will try to help you.

Konstruktor​

Installing Konstruktor​

Konstruktor is a small application based on the Tauri-Framework, which is still in active development, however we have not encountered any problems with it so far. It should work on all major platforms and we have tested the installation with Windows 10, Mac OS and Ubuntu 20.04. If you encounter any issues in the installation please make sure you have the latest version of Konstruktor installed. You can find the latest version here.

Crashing Konstruktor​

This is definelty a bug from our side. Please post a screenshot of the crashed application and the error message as an Issue in our Konstruktor GitHub. Sorry about that!

Konstruktor couldn't find Docker​

This is a common problem, and it's usually not a problem with Konstruktor, but with your installation of Docker, or because Docker is not running. Konstruktor will both tryto interface with your docker instance through the docker cli (command line interface) and through the docker socket. The majority of the interaction will happen through the docker cli (command line interface), but some operations, like inspecting the docker network, will require the docker socket.

Try the following steps to debug your docker installation:

  1. Check if you have Docker installed and running. If you start docker after you started Konstruktor, you will need to restart Konstruktor.

  2. Check if you have Docker the docker CLI installed and running. You can do this by opening a terminal (cmd) and running the following command:

    docker ps

    If you get an error message, docker is not running. If you get a list of running containers, docker is running.

  3. Check if you can run a docker container. You can do this by running the following command:

    docker run hello-world

    If you get an error message, docker is not running. If you get a message that the container was started successfully, docker is running.

If all of these steps work, but Konstruktor still can't find docker, please open an Issue on our GitHub. Sorry about that!

Couldn't install from Paper channel​

Channels are Konstruktor ways of creating a new deployment. You can think of them as templates. These templates are stored in a GitHub repository, and Konstruktor will try to download them from there. In the default configuration, Konstruktor will try to download the templates from the konstruktor repository. So make sure you have an internet connection, and that you can access GitHub. If you are behind a firewall, you might need to allow Konstruktor to access the Internet.

Konstruktor couldn't find my GPU​

Konstruktor not being able to detect your GPU is not a problem of it one, your Arkitekt instance should still eb able to run, you might just not be able to use GPU accelerated services. This step is just a warning, and you can safely ignore it if you don't need GPU acceleration.

If you are certain however that you have a GPU installed, and you want to use GPU accelerated services, you can try the following steps:

  1. Make sure you have a GPU installed that supports CUDA. You can find a list of supported GPUs here. Here Nvidia lists the Computey capability of each GPU. CUDA 11 supports GPUs with a compute capability of a least 3.5 to 8.x. So, if you want your GPU to support CUDA 11, it should have at least a compute capability of 3.5. However, if you're aiming to leverage all features and optimizations provided by CUDA 11, it's preferable to have a newer GPU with a higher compute capability.

  2. Make sure you have the latest NVIDIA drivers installed on your computer. You can find the latest drivers here. If you are using a laptop, you might need to download the drivers from the website of your laptop manufacturer.

  3. When checking your GPU, Konstruktor will check if Docker can run a container with the nvidia/cuda image. It will NOT check your CUDA installation diretly. This means that if you have CUDA installed, but Docker is not running, Konstruktor will still not be able to detect your GPU. The output of the nvidia-smi command inside the docker will be used to detect your GPU. However sometimes this command will fail, even if you have a GPU installed. Just check the LOGS section. If it looks like it detected your GPU correctly, you can safely ignore this warning. But please open an issue on our GitHub and let us know about it.

  4. Again: You do NOT need to install CUDA or CUDNN. Arkitekt Containers utilize the nvidia/cuda docker image, which already contains all the necessary libraries.

  5. You can also test if your GPU is working correctly by running the following command in a terminal (cmd):

    docker run --gpus all nvidia/cuda:11.0-base nvidia-smi

    If you get an error message, you cannot access your GPU. If you get a list of information about your GPU, you can access your GPU :).

  6. If Konstruktor claims to have not found your GPU, but you are certain that you have a compatible GPU installed, and you have the latest drivers installed, please open an Issue on our GitHub

Konstruktor showed me an error message​

That sounds like an error on our side. Please open an Issue on our GitHub. Sorry about that! You can defintely help us by posting a screenshot of the error message. Sometimes a restart might help!

The Deployment​

I couldn't open the Dashboard of my Deployment​

If you can't open the Dashboard of your Deployment, but it appears on the Dashboard of Konstruktor, its probably because there is some file permission errors and Konstruktor can't access the files of your Deployment. This can happen if you are using Linux and you are running Konstruktor as root. Konstruktor will then create files that are only accessible by root, and you won't be able to access them. You can fix this by changing the permissions of the files. You can do this by running the following command in the folder where your Deployment is located.

sudo chown -R $USER:$USER .

I couldn't initialize my Deployment​

The initialization of a Deployment is a very time consuming process. It can take up to 10 minutes, depending on your internet connection and hardware. During the initialization, Konstruktor will download all the necessary docker images for your Deployment. This can take a while. So please be patient. You should be able to see the progress in the popup window. If you are prompted with an error message. Please let us know !

I couldn't start my Deployment​

After initialization you should be able to start your Deployment. This will take a few seconds and you should slowly see the services turning green. However if you are prompted with an error message, please let us know !

Here are a few things you can try to debug your Deployment:

  • If docker complains about occupied ports, you might have another service running on the same port. That blocks the Arkitekt server. If this is the case please stop the service and try again. Arkitekt in its default configuration allocates ports 8000, 8010, 8020, 8030, 8040, 8050, 8060, and 8061. If one of these ports is blocked the service will not start and you will be prompted with an error message.

  • If docker complains about not being able to pull an image, please check your internet connection. If you are behind a firewall,you might need to allow the docker daemon to access the internet. If you are using a proxy, you might need to configure docker to use the proxy. You can find more information about this here

  • If docker complains about not being able to find an image, please check if you have the latest version of Konstruktor installed. You can find the latest version here. If you are using a custom channel, please make sure that the channel is still available. If you are using the default channel, please let us know!

  • Konstruktor can also update your deployment to the latest version. Just click on the Danger button in the Dashboard. Which allows you to maintain your deployment.

I can't see the logs of my Deployment​

If you want to inspect why an service might be experiencing errors you can check the logs of the service. You can do this by clicking on the service in the Dashboard. This will open a popup window with the logs of the service. If no logs appear, your docker socket might be blocked. On a Windows machine, you might need to check if the docker socket is exposed. You can do this by opening the settings of Docker and checking the Expose daemon on tcp://localhost:2375 without TLS option. Make sure to restart Docker after you changed the settings.

If you still cant see the logs, you can also open the folder of your deployment (by clicking on the deployment name in the dashboard), and run the following command in a terminal (cmd), with the current working directory being the folder of your deployment:

docker compose logs

or

docker compose logs $SERVICE_NAME

With service name being the logs of the service you want to inspect. You can find the service name in the docker-compose.yml file of your deployment.

The services of my deployment keep crashing​

That's bad. This can have many reasons. If a service crashes, it will be restarted automatically. If it keeps crashing, it will be restarted a few times, and then the deployment will be stopped. You can check the logs of the service to see why it crashed. You can do this by clicking on the service in the Dashboard. See if you can find the error message. Attach the error message to an Issue on our GitHub. We will try to help you!

I never see all my services turn green​

Green services are Arkitekt services, that are running and ready to be used. For this to happen, all services need to be running and ready, and have passed some "health" checks that Konstruktor is subjecting it to. If you have a service that is not turning green, it means that it is not ready yet. If you just started your deployment, it might take a few minutes for all services to turn green, as they will perform some initialization steps. If you have a service that is not turning green, for a long time (> 40 seconds), it is probably failing. There is however two types of failure:

  • Docker failure: If the service is failing because of a docker error, the whole deployment will be marked red, including the Container (inner card inside the service card). You can check the logs of the service to see why it crashed. You can do this by clicking on the service in the Dashboard. Try to restart the service. This can help sometimes.

  • Healthcheck failure: If the Container marked (inner card) is safely green, but the top right indicator is not green, it means that the service is failing some health checks. This can happen if the service is not ready yet, or any service it depends on is not ready yet. Just click on the Open Health and inspect the health of the service. Try restarting that service. This can help sometimes.

Anyhow if you have a service that is not turning green, please open an Issue on our GitHub. We will try to help you!

I couldn't advertise my Deployment​

Advertising your Deployment will set your Konstruktor instance as a "Beacon". It will send out messages inside your network (UDP Broadcast) that will allow other all Apps to discover your Deployment. For this to work, you need to have UDP Broadcast enabled in your network (which we will check for), and your network needs to tell us your IP address (which we will also check for). By default Konstruktor will not advertise but wait for you to check the network interfaces you want to advertise on. For this to work, you need to make sure that your firewall allows these broadcasts.

On Advertising

Importantly it will also stop when you close Konstruktor. So if you want to advertise your Deployment, you need to keep Konstruktor open.

Advertising your Deployment is not necessary for it to work. It is just a convenience feature that allows you to discover your Deployment from other Apps. If apps are not able to discover your Deployment, or you experience any other issue please open an Issue on our GitHub. We will try to help you!

My Deployment is running, but it doesnt appear in Orkestrator​

If your Deployment is running, but it doesn't appear in Orkestrator, it means that Orkestrator was not able to discover your Deployment. This can have many reasons.

  1. Check if your Deployment is really running (i.e. all services are green). If your Deployment is not running, Orkestrator will not be able to discover it.

  2. Restart Discovery. Depending if your are using the Desktop App or the Webrowser:

    • Desktop App: Restart the whole App.
    • Webbrowser: Reload the webpage.

  3. Make sure you share the same network as your deployment.

  4. For automatic detection: Make sure that:

    • You are on the same machine as your deployment when using Webbrowser. (e.g you are able to access localhost:8000)
    • You are on the same network as your deployment when using the Desktop App and you advertise your deployment on the correct network interface.

  5. For manual connection. If the automatic steps fail, you can always try to manually connect your instance by entering in the ipaddr or hostname of your deployment followed by the Lok Service Port (8000) in the Advanced Connect tab of Orkestrator. Here you should enter hostnameofcomputer:8000 or ipaddr:8000

I can't access my server from another computer​

If you can't access your server from another computer, it means that your server is not reachable from the outside. This can have many reasons:

  1. Make sure you share the same network as your deployment.
  2. Make sure you are using the correct IP address. Or if you are using a hostname, make sure that the hostname is resolvable.
  3. Make sure you are using the correct port for the Lok service. By default Arkitekt uses port 8000. If you are using a different port, make sure you are using the correct one.
  4. Make sure your firewall allows incoming connections on the Lok service port. By default Arkitekt uses port 8000.
  5. Try to advertise your deployment on other network interfaces.