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 deplo.io 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

Lets Encrypt certificates

Applications on deplo.io 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 deplo.io 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 deplo.io 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 deplo.io 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 deplo.io. 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 deplo.io (as deplo.io does not support IPv6 currently).