Skip to main content

Troubleshooting and advanced topics

How it works behind the scenes​

To understand and be able to troubleshoot issues when deploying your app, it helps to know a bit about what is going on in the backend. This is what happens on a high level during a successful app creation:

  • Git repository is cloned at whatever revision was specified
  • The language of the app gets detected
  • The app is being built and package into a OCI container with language-appropriate tools
  • The built app image is uploaded to the Deploio image registry
  • A release is created which executes the previously built image
  • The application is exposed on an HTTP endpoint

The build and release step is where most things can go wrong. If there's an error or incompatibility within the cloning or build step, nctl will show the build logs to help with troubleshooting. If the build is successful but a release does not become ready, usually there should be an indication about the problem in the app logs. Of course if your app fails silently on start, the app log might be empty.

Retry build​

The build may fail due to multiple reasons. Most of the time a change on the application code or a missing environment/build variable will fix the issue, but it might happen that some temporary internal system issue failed the build. In those cases you can retry the build by using nctl:

$ nctl update app go-example --retry-build

Inspecting and running the build output locally​

As the build output is just an OCI/Docker image, it's possible to pull the image to your local machine to inspect it. This can be helpful if the build succeeds but the release fails to start the app. Note that it's just possible to pull images for debugging, pushing images to the registry is disabled.

$ nctl get build go-example-build-1 --pull-image
Pulling image of build go-example-build-1
739cb80086f0: Download complete
1bfd697887fa: Download complete
aea73d1e202c: Download complete
e4fd482e7de7: Download complete
 ✓ Pulled image deploio.296dc8b.registry.nineapis.ch/nine/go-example 💾

After downloading the image, you can interact with it using Docker or Podman (or anything that can interact with OCI images) to inspect and run the image locally.

$ docker run deploio.296dc8b.registry.nineapis.ch/nine/go-example

Executing a shell or command in a Deploio application​

You can start a shell in your Deploio application once it was released successfully. Please note that your application needs to already run in a stable way so that a shell can be started. If your application constantly restarts because of an error, starting a shell will not be possible.

You can start a shell with the help of nctl. This will start a shell in the first Deploio replica which can be found.

$ nctl get app
NAME     HOSTS                        UNVERIFIED_HOSTS
rails    rails.7f0b629.deploio.app    none

$ nctl exec app rails
cnb@rails-5fcc67cc-89fd2:/workspace$

You can also start a single command by separating it with --.

$ nctl exec app rails -- hostname
rails-5fcc67cc-89fd2

Please note, that every command you start will be counted towards your memory quota which depends on your configured Deploio application size. If too much memory is used the whole Deploio application replica will be terminated and you will most probably see an exit code of 137:

nctl: error: command terminated with exit code 137

Furthermore, any change to local files being done in a shell session will be lost, once the Deploio replica was restarted.

Lets Encrypt certificates​

Applications on Deploio are exposed via a random generated URL by default. That way you can access your application during development time without the need for an own domain name. The default URL is also secured by a Lets Encrypt TLS certificate which gets directly generated when you create a Deploio application. For Lets Encrypt certificates, the HTTP-01 challenge type is generally used. You can see the status of the default URLs Lets Encrypt certificate via nctl:

nctl get app <APP NAME> -o yaml

kind: Application
apiVersion: apps.nine.ch/v1alpha1
...
status:
  atProvider:
    ...
    defaultHostsCertificateStatus: Issued

Whenever you add custom host names to your Deploio application, a corresponding Lets Encrypt TLS certificate will be issued for all your custom host names. You can see the status of that certificate via nctl as well:

nctl get app <APP NAME> -o yaml

kind: Application
apiVersion: apps.nine.ch/v1alpha1
...
status:
  atProvider:
    ...
    customHostsCertificateStatus: Pending

As we are using the Lets Encrypt HTTP-01 challenge type, the certificate will only be successfully issued once all of your custom hostnames point to the Deploio infrastructure. We are using an optimized DNS resolving path to quickly react to DNS changes, but it might still take some minutes before the certificate can be issued. This is especially important if you migrate an application which is elsewhere hosted to Deploio. As the transition can take some minutes, please consider a migration during non-business hours.

Please also keep in mind that Lets Encrypt favors IPv6 DNS entries over IP4 ones. So if you have DNS AAAA records for your custom hostnames, make sure to delete them when migrating to Deploio (as Deploio does not support IPv6 currently).