From 1fb79b4fe13f689bc8d2b6b0f91f1155699ae169 Mon Sep 17 00:00:00 2001 From: Benjamin ACH Date: Thu, 30 Apr 2026 11:26:46 +0200 Subject: [PATCH] docs(app): add dedicated Troubleshooting page --- _config.yml | 2 +- assets/style.css | 60 +++++ redirections.yml | 9 + src/_includes/language_start_pages.md | 13 ++ src/_plugins/jekyll-deploytl-tag.rb | 52 +++++ src/_posts/platform/app/2000-01-01-crash.md | 218 ------------------ .../app/2000-01-01-postdeploy-hook.md | 4 +- .../platform/app/2000-01-01-procfile.md | 8 +- .../app/2000-01-01-troubleshooting.md | 3 + .../troubleshooting/2000-01-01-boot-errors.md | 103 +++++++++ .../2000-01-01-deployment-issues.md | 138 +++++++++++ .../2000-01-01-runtime-issues.md | 116 ++++++++++ .../2000-01-01-common-deployment-errors.md | 206 ----------------- .../getting-started/2000-01-01-first-steps.md | 34 +-- .../2000-01-01-setup-git-windows.md | 2 +- .../2000-01-01-setup-ssh-linux.md | 6 +- .../2000-01-01-setup-ssh-macos.md | 10 +- .../2000-01-01-setup-ssh-windows.md | 28 ++- .../2000-01-01-container-management.md | 4 +- src/_posts/tools/cli/2000-01-01-start.md | 6 +- 20 files changed, 554 insertions(+), 468 deletions(-) create mode 100644 src/_includes/language_start_pages.md create mode 100644 src/_plugins/jekyll-deploytl-tag.rb delete mode 100644 src/_posts/platform/app/2000-01-01-crash.md create mode 100644 src/_posts/platform/app/2000-01-01-troubleshooting.md create mode 100644 src/_posts/platform/app/troubleshooting/2000-01-01-boot-errors.md create mode 100644 src/_posts/platform/app/troubleshooting/2000-01-01-deployment-issues.md create mode 100644 src/_posts/platform/app/troubleshooting/2000-01-01-runtime-issues.md delete mode 100644 src/_posts/platform/getting-started/2000-01-01-common-deployment-errors.md diff --git a/_config.yml b/_config.yml index 3f8eaa7ef..61a7ae964 100644 --- a/_config.yml +++ b/_config.yml @@ -78,7 +78,7 @@ highlighted: - /tools/cli/start - /platform/app/log-drain - /platform/deployment/deployment-process - - /platform/getting-started/common-deployment-errors + - /platform/app/troubleshooting/deployment-issues - /languages/nodejs/start - /languages/php/start - /databases/postgresql/about/overview diff --git a/assets/style.css b/assets/style.css index 8d581ec77..7ad4fa7b7 100644 --- a/assets/style.css +++ b/assets/style.css @@ -1134,3 +1134,63 @@ source: https://weblog.west-wind.com/posts/2016/feb/15/flexbox-containers-pre-ta div, span, html, body, ul, article, main, nav { min-width: 0; } + + +ol.deploy-timeline { + border-left: 4px solid var(--color-primary-gray-200); + margin: 1rem 0 1rem 1rem; + + li { + display: flex; + font-weight: 300; + line-height: 2rem; + list-style-type: none; + margin-left: -1.1rem; + padding: 0; + + &::before { + background-color: var(--color-primary-gray-200); + border-radius: 50%; + border: 1px solid var(--color-primary-gray-200); + color: #FFF; + content: "\00A0"; /* non-breakbale space */ + display: inline-block; + font-family: var(--font-mono); + font-size: 1.25rem; + font-weight: 600; + height: 2rem; + line-height: 2rem; + margin-right: 1rem; + text-align: center; + width: 2rem; + } + + &.ok { + font-weight: 400; + + &::before { + background-color: var(--color-state-success-700); + content: "\2713"; /* ✓ (check mark) */ + } + } + + &.cur { + font-weight: 600; + + &::before { + background-color: var(--color-warning-500); + content: "\2022"; /* • (bullet) */ + } + } + + span { + background-color: var(--color-primary-gray-200); + border-radius: 5px; + font-family: var(--font-mono); + font-size: 0.8rem; + font-weight: 400; + margin-right: 1rem; + padding: 0 0.5rem; + } + } +} diff --git a/redirections.yml b/redirections.yml index eba8ebb03..e70221531 100644 --- a/redirections.yml +++ b/redirections.yml @@ -864,6 +864,15 @@ - old: "/platform/app/notification" new: "/platform/app/notifiers" + - old: "/platform/getting-started/common-deployment-errors" + new: "/platform/app/troubleshooting/deployment-issues" + + - old: "/platform/app/crash" + new: "/platform/app/troubleshooting/boot-errors" + + - old: "/platform/deployment/unknown-technology" + new: "/platform/app/troubleshooting/deployment-issues#unknown-technology" + obsolete: - "/how-to-migrate-from-cloudcontrol/" - "/how-to-migrate-from-shelly-cloud/" diff --git a/src/_includes/language_start_pages.md b/src/_includes/language_start_pages.md new file mode 100644 index 000000000..de84861a8 --- /dev/null +++ b/src/_includes/language_start_pages.md @@ -0,0 +1,13 @@ +{::comment} +Keep this list sorted alphabetically to match the detection order. +{:/comment} +* [Clojure]({% post_url languages/clojure/2000-01-01-start %}) +* [Go]({% post_url languages/go/2000-01-01-start %}) +* [Groovy]({% post_url languages/groovy/2000-01-01-start %}) +* [Java]({% post_url languages/java/2000-01-01-start %}) +* [Meteor]({% post_url languages/meteorjs/2000-01-01-start %}) +* [Node.js]({% post_url languages/nodejs/2000-01-01-start %}) +* [PHP]({% post_url languages/php/2000-01-01-start %}) +* [Python]({% post_url languages/python/2000-01-01-start %}) +* [Ruby]({% post_url languages/ruby/2000-01-01-start %}) +* [Scala]({% post_url languages/scala/2000-01-01-start %}) diff --git a/src/_plugins/jekyll-deploytl-tag.rb b/src/_plugins/jekyll-deploytl-tag.rb new file mode 100644 index 000000000..27f8e20f9 --- /dev/null +++ b/src/_plugins/jekyll-deploytl-tag.rb @@ -0,0 +1,52 @@ +module Jekyll + class DeployTimelineTag < Liquid::Tag + def initialize(tag_name, markup, tokens) + super + @steps = parse_steps(markup) + end + + def render(context) + first_ok = @steps.min + + html = "
    \n" + html << %Q{building Source fetched\n} + html << %Q{building Technology detected\n} + html << %Q{building Application image built\n} + html << %Q{starting Container started\n} + html << %Q{starting Postdeploy hook run\n} + html << %Q{running  Application running\n} + html << "
" + + html + end + + private + + def class_attr(step, first_ok) + if @steps.include?(step) + ' class="cur"' + elsif first_ok && step < first_ok + ' class="ok"' + else + '' + end + end + + def parse_steps(markup) + match = markup.match(/steps="([^"]+)"/) + return [] unless match + + value = match[1] + + if value.include?("-") + start_s, end_s = value.split("-").map(&:to_i) + (start_s..end_s).to_a + else + [value.to_i] + end + end + end +end + + +Liquid::Template.register_tag("deploytl", Jekyll::DeployTimelineTag) diff --git a/src/_posts/platform/app/2000-01-01-crash.md b/src/_posts/platform/app/2000-01-01-crash.md deleted file mode 100644 index bbb13273e..000000000 --- a/src/_posts/platform/app/2000-01-01-crash.md +++ /dev/null @@ -1,218 +0,0 @@ ---- -title: Application Crash -modified_at: 2023-05-24 00:00:00 -tags: app crash recovery -index: 12 ---- - -When the platform starts your container(s) (be it after a successful build, -after a scale operation or after a restart operation), your application enters -the *run* phase of its [lifespan]({% post_url platform/internals/2000-01-01-container-management %}). -Unfortunately, bad things may still happen during this phase, which can lead -your application to crash. - -Various reasons can explain why your application's lifespan ends up shortened. -At Scalingo, we distinguish two main kinds of crash: -**[Boot Errors](#understanding-boot-errors)** and -**[Runtime Errors](#understanding-runtime-errors)**. - - -## Understanding Boot Errors - -**Boot Errors** can only occur when your container is still in its *starting* -state, **before** entering its *running* state. - -These errors are thrown by the platform when it detects that your application -doesn't behave as expected. - -There are 3 kinds of Boot Errors: -[Start Errors](#understanding-start-errors), -[Timeout Errors](#understanding-timeout-errors) and -[Hook Errors](#understanding-hook-errors). - -### Understanding Start Errors - -The **Start Error** is the default kind of Boot Error. It is thrown as soon as -an unmanaged error is detected and caught by the platform. It can occur at any -moment, as long as your app isn't *running* yet. - -A Start Error makes the deployment fail instantly. Note that the former version -of your application (if any), keeps running. - -In most cases, a Start Error is caused by a misconfiguration of your -application, or by some unmanaged error/exception in your application's code. - -#### Fixing Start Errors - -It's very likely that an action on your side is required to fix the issue. The -deployment logs should help you identify the issue. - -### Understanding Timeout Errors - -When your application has a [`web` or a `tcp` process type]({% post_url platform/app/2000-01-01-procfile %}#special-process-types), -the process started in the corresponding container(s) **MUST** bind to the -provided network port (`PORT` environment variable) within a delay of 60 -seconds. After this deadline, the platform considers the application has being -unreachable and throws a **Timeout Error**, causing the deployment to fail. - -- If this situation arises after a restart or a scale operation, the platform - automatically retries to start your container(s). After 20 unsuccessful - attempts (with an exponential backoff strategy), the platform gives up. - Note that your existing containers keep running during this time and after. - -- If you are trying to deploy a new version of an already running application, - this new deployment is considered a failure but the previous version of your - application keeps running. - -- Conversely, if this is a very first deployment, the platform does not make - any attempt to recover from the error. The deployment fails with a - **timeout-error** status, letting you know that your application didn't - bind to `PORT` soon enough. - -{% note %} - A Timeout Error can only occur if you have a `web` or a `tcp` process type, - which is very likely. -{% endnote %} - -#### Fixing Timeout Errors - -To fix a Timeout Error, make sure: -- to bind to the provided network port, by using the `PORT` environment - variable. -- to listen on `0.0.0.0` and not on `127.0.0.1`. -- that your application is starting quickly enough. - -You may need to edit your -[Procfile]({% post_url platform/app/2000-01-01-procfile %}) to fulfill these -requirements. - -If your application doesn't need a `web` or `tcp` process type, make sure to -[scale the unnecessary process type to zero]({% post_url platform/app/2000-01-01-web-less-app %}#deploy-a-web-less-application). - -### Understanding Hook Errors - -If your application has a [`postdeploy` process type]({% post_url platform/app/2000-01-01-procfile %}#special-process-types), -the platform can throw a **Hook Error** if the post-deployment process fails. - -- In such a case, the deployment fails with a **hook-error** status. -- If your application is already running, its code isn't updated and the former - version keeps running. - -{% note %} - Hook Errors can only occur if you have a `postdeploy` process type. -{% endnote %} - -#### Fixing Hook Errors - -Hook Errors are generally caused by an error in your codebase or by some -misconfiguration. To recover from it, we first advise to investigate the logs -of your application to understand the root cause. After fixing it, trigger a -new deployment by pushing your updated code to Scalingo. - - -## Understanding Runtime Errors - -**Runtime Errors** are errors that happen during the execution of the process. -Per definition, they can only occur when your container has reached its -*running* state (which means your deployment is considered successful by the -platform). - -Unfortunately, and even if it has reached this state, unexpected errors can -still lead your application to crash. - -The most common causes are: - -- Incompatible dependencies -- Segfault of a library/runtime -- Configuration issues -- Bugs in your application code -- Uncaught exception in your code (especially with non-compiled languages) -- Unsufficient resources -- Temporary error/unavailability of an external resource - -A Runtime Error can have several consequences, depending on the severity of the -error and the impact it has on your application: - -- Reduced Performances: slow response time typically result in poor user - experience. -- Downtime: the unavailability of your application, even if temporary, can have - a significant impact on business operations. -- Data loss, or Corrupt Data: losing strategic data can have serious - consequences for your organization or for your users/customers, especially in - an [HDS context]({% post_url compliance/2000-01-01-hds %}). -- Security Risks: runtime errors can sometimes introduce security risks, - especially if your application is too verbose. This can lead to sensitive - data leak and further exploitation. - -### Mitigating and Preventing Runtime Errors - -The very first step to take to mitigate the consequences of a Runtime Error is -to ensure that you have regular, tested backups (for databases, this feature is -included in all our *business* plans) and to setup some -[redundancy]({% post_url platform/app/scaling/2000-01-01-scaling %}#redundancy). - -Additionally, we generally advise to have a disaster recovery plan in place. -This plan should ideally outline the actions to be taken in the event of such a -failure. It may include procedures and step by step guides to identify and -resolve the encountered error. - -We also recommend to regularly check the application's health. This can be -done by checking the metrics, analyzing the logs, or setting up automated -anomaly detection. The goal is to identify and fix potential issues before they -occur. - -Finally, we strongly encourage developers to test their code, to follow the -best practices and to conduct Q/A testings in a dedicated environment before -migrating to production. - -### Recovering from a Runtime Error - -When a Runtime Error occurs and leads to an application crash, the platform -automatically takes some remedial measures to try to recover from it. The very -first action consists in logging the crash event in your dashboard. Once done, -the platform uses its restart policy, described hereafter: - -The platform maintains a crash counter for each running container. This crash -counter is set to zero by default. - -When a container crashes for the first time (when its crash counter equals -zero), the platform sets the crash counter to one and then tries to restart the -container. This is done as soon as the failure is detected. - -After a successful restart, the container enters a *warmup* period which always -lasts 10 minutes. From here, we distinguish two main cases: - -1. The container successfully goes past the *warmup* period. In this case, the - platform considers that the restart operation fixed the issue and thus - resets the container's crash counter to zero. - -2. The container crashes again during the *warmup* period. In this case, the - platform immediately increments the crash counter by one. - - If the crash counter value is less than 13, then the platform waits some - time before restarting the container again. The duration of the waiting - period is given by the following formula: - `duration (minutes) = (crash counter value - 2) x 5` - - If the crash counter value equals 2, 5 or 12, the platform sends a warning - e-mail to the application's collaborators. - - If the crash counter value reaches 13, which means the container keeps - crashing after 12 delayed restarts, the platform gives up. The container - is crashed and won't be restarted anymore, which means your application - may now be totally unavailable. - -#### Fixing Runtime Errors - -Besides the measures taken by the platform, we strongly advise you to carefully -investigate the logs of your crashing application as soon as possible. Once -your fix is ready, push your updated code to Scalingo to trigger a new -deployment, hopefully resolving the issue. - -## Getting Notified When a Crash Occurs - -By default, the platform only notifies the application's collaborator(s) when -a recurrent crash occurs (i.e. when an early Runtime Error keeps occuring, or -when a Timeout Error occurs). - -You can modify this behavior by tweaking your -[app notifier configuration]({% post_url platform/app/2000-01-01-notifiers %}). -The `app_crashed`, `app_crashed_repeated` and the `app_deployed` events can be -particularly worth considering. diff --git a/src/_posts/platform/app/2000-01-01-postdeploy-hook.md b/src/_posts/platform/app/2000-01-01-postdeploy-hook.md index 8af073f20..05283bf5f 100644 --- a/src/_posts/platform/app/2000-01-01-postdeploy-hook.md +++ b/src/_posts/platform/app/2000-01-01-postdeploy-hook.md @@ -1,6 +1,6 @@ --- title: Post-deployment hook -modified_at: 2023-12-22 00:00:00 +modified_at: 2026-04-29 00:00:00 tags: app deployment hook postdeploy index: 13 --- @@ -32,7 +32,7 @@ happen in the following order: 2. Containers from the new version of the application are started 3. We wait until they started successfully (see common [deployment start errors]({% post_url - platform/getting-started/2000-01-01-common-deployment-errors + platform/app/troubleshooting/2000-01-01-boot-errors %}#start-errors)). They are not reachable yet, see [limits](#limits) below. 4. An extra container is started to run the `postdeploy` command 5. If the `postdeploy` command succeeds, we update the routing diff --git a/src/_posts/platform/app/2000-01-01-procfile.md b/src/_posts/platform/app/2000-01-01-procfile.md index 5de477d88..54e38e3ee 100644 --- a/src/_posts/platform/app/2000-01-01-procfile.md +++ b/src/_posts/platform/app/2000-01-01-procfile.md @@ -2,7 +2,7 @@ index: 11 title: Procfile tags: internals process types procfile heroku -modified_at: 2026-03-05 12:00:00 +modified_at: 2026-04-29 00:00:00 --- Procfile support is one of our @@ -118,7 +118,7 @@ uses the YAML syntax, there is **no extension**: no `.txt`, no `.yaml`, no `.yml`. **Only `Procfile`**. The file MUST live in your application's root directory or in `$PROJECT_DIR`, -if your [application code lies in a subdirectory of your repository]({% post_url platform/getting-started/2000-01-01-common-deployment-errors %}#project-in-a-subdirectory). +if your [application code lies in a subdirectory of your repository]({% post_url platform/app/troubleshooting/2000-01-01-deployment-issues %}#project-in-a-subdirectory). ### Defining a Process Type @@ -185,10 +185,10 @@ web: bash bin/start.sh ### Starting and Stopping a Process Type -When starting or stopping a process type, you concretly instruct the platform +When starting or stopping a process type, you concretely instruct the platform to create (and start) or stop (and destroy) all the container(s) referenced by this process type. In fact, these operations are the same and consist in -**scaling** the process type, which can be done via the dashbord or via the +**scaling** the process type, which can be done via the dashboard or via the CLI. All **new** process types are considered to be scaled to 0:M by default and, diff --git a/src/_posts/platform/app/2000-01-01-troubleshooting.md b/src/_posts/platform/app/2000-01-01-troubleshooting.md new file mode 100644 index 000000000..b637975fc --- /dev/null +++ b/src/_posts/platform/app/2000-01-01-troubleshooting.md @@ -0,0 +1,3 @@ +--- +index: 12 +--- diff --git a/src/_posts/platform/app/troubleshooting/2000-01-01-boot-errors.md b/src/_posts/platform/app/troubleshooting/2000-01-01-boot-errors.md new file mode 100644 index 000000000..1c2375c0a --- /dev/null +++ b/src/_posts/platform/app/troubleshooting/2000-01-01-boot-errors.md @@ -0,0 +1,103 @@ +--- +title: Boot Errors +modified_at: 2026-05-05 00:00:00 +tags: app deployment boot startup timeout hook troubleshooting +index: 2 +--- + +**Boot Errors** can only occur when your container is still in its *starting* +state, **before** entering the *running* state of its [lifespan]: + +{% deploytl steps="4-5" %} + +These errors are thrown by the platform when it detects that your application +doesn't behave as expected. + +There are 3 kinds of Boot Errors: [Start Errors](#start-errors), +[Timeout Errors](#timeout-errors) and [Hook Errors](#hook-errors). + + +## Start Errors + +The **Start Error** is the default kind of Boot Error. It is thrown as soon as +an unmanaged error is detected and caught by the platform. It can occur at any +moment, as long as your app isn't *running* yet. + +A Start Error makes the deployment fails instantly. Note that the former version +of your application (if any), keeps running. + +In most cases, a Start Error is caused by a misconfiguration of your +application, or by some unmanaged error/exception in your application's code. + +### Fixing Start Errors + +It's very likely that an action on your side is required to fix the issue. The +deployment logs should help you identify the issue. + + +## Timeout Errors + +When your application has a [`web` or a `tcp` process type][procfile-special], +the process started in the corresponding container(s) **MUST** bind to the +provided network port (`PORT` environment variable) within a delay of 60 +seconds. After this deadline, the platform considers the application has been +unreachable and throws a **Timeout Error**, causing the deployment to fail. + +- If this situation arises after a restart or a scale operation, the platform + automatically retries to start your container(s). After 20 unsuccessful + attempts (with an exponential backoff strategy), the platform gives up. + Note that your existing containers keep running during this time and after. + +- If you are trying to deploy a new version of an already running application, + this new deployment is considered a failure but the previous version of your + application keeps running. + +- Conversely, if this is a very first deployment, the platform does not make + any attempt to recover from the error. The deployment fails with a + **timeout-error** status, letting you know that your application didn't + bind to `PORT` soon enough. + +{% note %} + A Timeout Error can only occur if you have a `web` or a `tcp` process type, + which is very likely. +{% endnote %} + +### Fixing Timeout Errors + +To fix a Timeout Error, make sure: +- to bind to the provided network port, by using the `PORT` environment + variable. +- to listen on `0.0.0.0` and not on `127.0.0.1`. +- that your application is starting quickly enough. + +You may need to edit your [Procfile] to fulfill these requirements. + +If your application doesn't need a `web` or `tcp` process type, make sure to +[scale the unnecessary process type to zero][webless]. + + +## Hook Errors + +If your application has a [`postdeploy` process type][procfile-special], +the platform can throw a **Hook Error** if the post-deployment process fails. + +- In such a case, the deployment fails with a **hook-error** status. +- If your application is already running, its code isn't updated and the former + version keeps running. + +{% note %} + Hook Errors can only occur if you have a `postdeploy` process type. +{% endnote %} + +### Fixing Hook Errors + +Hook Errors are generally caused by an error in your codebase or by some +misconfiguration. To recover from it, we first advise to investigate **your +application logs**, not the deployment logs, to understand the root cause. After +fixing it, trigger a new deployment by pushing your updated code to Scalingo. + + +[lifespan]: {% post_url platform/internals/2000-01-01-container-management %} +[webless]: {% post_url platform/app/2000-01-01-web-less-app %}#deploy-a-web-less-application +[Procfile]: {% post_url platform/app/2000-01-01-procfile %} +[procfile-special]: {% post_url platform/app/2000-01-01-procfile %}#special-process-types diff --git a/src/_posts/platform/app/troubleshooting/2000-01-01-deployment-issues.md b/src/_posts/platform/app/troubleshooting/2000-01-01-deployment-issues.md new file mode 100644 index 000000000..41230089a --- /dev/null +++ b/src/_posts/platform/app/troubleshooting/2000-01-01-deployment-issues.md @@ -0,0 +1,138 @@ +--- +title: Deployment Issues +modified_at: 2026-04-30 00:00:00 +tags: app deployment troubleshooting buildpack build errors +index: 1 +--- + +This page gathers common issues that can happen before an application image is +ready to start. + +{% deploytl steps="1-2-3" %} + + +## Unknown Technology + +When pushing your app to Scalingo, you might get the following error: + +```text +<-- Start deployment of [my-app] --> + ! We didn't find the type of technology you are using... + We're sorry this build is failing! + + Refer to the documentation to find out why: + https://doc.scalingo.com/deployment/unknown-technology + + If you can't find the issue in your application, + please send us an email at support@scalingo.com + + <3, + Scalingo + ! Error deploying the application + ! -> Invalid return code from buildpack +``` + +There are two main solutions to this problem. + +### Project in a Subdirectory (Monorepo) + +Your project might be located in a subdirectory of your Git repository, which +is common in monorepo setups. This is supported, but note that Scalingo's +deployment system looks at the repository root by default. + +You need to setup the `PROJECT_DIR` environment variable for your application. +See our dedicated page on +[environment variables]({% post_url platform/app/2000-01-01-environment %}). + +You can find more information about monorepo deployment in our +[dedicated guide]({% post_url platform/app/2000-01-01-monorepo %}). + +### Technology Detection + +To detect the technology used by your application, we iterate over the +technologies alphabetically. It means that if your project contains multiple +technologies, we will pick the first one detected. + +If you want to skip the detection phase and force the use of a specific +buildpack, add the environment variable `BUILDPACK_NAME` to your project. + +If you need to use multiple technologies, you can use the [multi-buildpacks]({% +post_url platform/deployment/buildpacks/2000-01-01-multi %}). + +You can also develop your own buildpack and add the environment variable +`BUILDPACK_URL` to have complete control on the detection and build phases. + +More information is available on [buildpacks]({% post_url +platform/deployment/buildpacks/2000-01-01-intro %}) or [multi-buildpacks]({% +post_url platform/deployment/buildpacks/2000-01-01-multi %}). + +Each language has its own expected files and conventions. Check the start page +for your application language: + +{% include language_start_pages.md %} + +## Git Submodule + +If your project repository uses Git submodules, please be aware that Scalingo +will not pull them. This Git feature is not supported on the platform for +different reasons. The main reason being that we currently have no way to +authenticate the `git pull` operation to a private Git repository when doing +the deployment. Actually Git submodules are often considered as a broken +feature of Git, that is why we do not encourage its usage or support it today. + +We recommend you to vendor a specific release of the code of the sub-git +repository in your main repository before pushing. + +## Build Errors + +During the deployment process, Scalingo first builds your application: its +dependencies are gathered and packaged into an **application image**. + +### Invalid Return Code From Buildpack + +Your application image is built using a buildpack ([List of buildpacks]({% +post_url platform/deployment/buildpacks/2000-01-01-intro %})). +If the buildpack exits with an error, it is probably linked to your project. +You should be able to see the content of the error in your console. Then adapt +your code according to it. + +If you think the error comes from our buildpacks, feel free to contact us and +we will fix it as soon as we can. + +### Image Too Large + +The maximum size of an application image is **2 GiB**. If your assets, your +dependencies, and your application code exceed this limit, you need to reduce +the size of the image before deployment: + +* Try to remove unused external dependencies or assets. +* Define a [`.slugignore` file]({% post_url platform/app/2000-01-01-slugignore %}) + to exclude files from the image. + +If you absolutely need all this data, please contact our support team. + +{% note %} + Keep your application image as small and lightweight as possible. Smaller + images help make builds, deployments, and application scaling faster and + smoother. +{% endnote %} + +### Archive Too Large + +When deploying an application, the Scalingo build system downloads the source +code as an archive. The maximum archive size is limited to **300 MB**. + +If your archive exceeds this limit you will get the following error: + +```text +Fail to fetch source code: fail to handle tgz: The archive is too heavy (more than 314572800 bytes) +``` + +{% note %} +The limit applies to the **uncompressed** archive. + +For example: given a **200 MB .tar.gz** archive, when the underlying **.tar** +archive is larger than **300 MB**, then you will encounter this limit. +{% endnote %} + +If you need to deploy a larger archive, please contact our support team. diff --git a/src/_posts/platform/app/troubleshooting/2000-01-01-runtime-issues.md b/src/_posts/platform/app/troubleshooting/2000-01-01-runtime-issues.md new file mode 100644 index 000000000..031820d95 --- /dev/null +++ b/src/_posts/platform/app/troubleshooting/2000-01-01-runtime-issues.md @@ -0,0 +1,116 @@ +--- +title: Runtime Issues +modified_at: 2026-05-04 00:00:00 +tags: app runtime crash recovery troubleshooting +index: 3 +--- + +**Runtime Errors** are errors that happen during the execution of the process. +Per definition, they can only occur when your container has reached its +*running* state (which means your deployment is considered successful by the +platform): + +{% deploytl steps="6" %} + + +## Understanding Runtime Errors + +Unfortunately, and even if it has reached this state, unexpected errors can +still lead your application to crash. + +The most common causes are: + +- Incompatible dependencies +- Segfault of a library/runtime +- Configuration issues +- Bugs in your application code +- Uncaught exception in your code (especially with non-compiled languages) +- Insufficient resources +- Temporary error/unavailability of an external resource + +A Runtime Error can have several consequences, depending on the severity of the +error and the impact it has on your application: + +- Reduced performance: slow response time typically results in poor user + experience. +- Downtime: the unavailability of your application, even if temporary, can have + a significant impact on business operations. +- Data loss, or Corrupt Data: losing strategic data can have serious + consequences for your organization or for your users/customers, especially in + an [HDS context]({% post_url compliance/2000-01-01-hds %}). +- Security Risks: runtime errors can sometimes introduce security risks, + especially if your application is too verbose. This can lead to sensitive + data leak and further exploitation. + +## Mitigating and Preventing Runtime Errors + +The very first step to mitigate the consequences of a Runtime Error is +to ensure that you have regular, tested backups (for databases, this feature is +included in all our *business* plans) and to setup some +[redundancy]({% post_url platform/app/scaling/2000-01-01-scaling %}#redundancy). + +Additionally, we generally advise to have a disaster recovery plan in place. +This plan should ideally outline the actions to be taken in the event of such a +failure. It may include procedures and step by step guides to identify and +resolve the encountered error. + +We also recommend to regularly check the application's health. This can be +done by checking the metrics, analyzing the logs, or setting up automated +anomaly detection. The goal is to identify and fix potential issues before they +occur. + +Finally, we strongly encourage developers to test their code, to follow the +best practices and to conduct Q/A testings in a dedicated environment before +migrating to production. + +## Recovering from a Runtime Error + +When a Runtime Error occurs and leads to an application crash, the platform +automatically takes some remedial measures to try to recover from it. The very +first action consists in logging the crash event in your dashboard. Once done, +the platform uses its restart policy, described hereafter: + +The platform maintains a crash counter for each running container. This crash +counter is set to zero by default. + +When a container crashes for the first time (when its crash counter equals +zero), the platform sets the crash counter to one and then tries to restart the +container. This is done as soon as the failure is detected. + +After a successful restart, the container enters a *warmup* period which always +lasts 10 minutes. From here, we distinguish two main cases: + +1. The container successfully goes past the *warmup* period. In this case, the + platform considers that the restart operation fixed the issue and thus + resets the container's crash counter to zero. + +2. The container crashes again during the *warmup* period. In this case, the + platform immediately increments the crash counter by one. + - If the crash counter value is less than 13, then the platform waits some + time before restarting the container again. The duration of the waiting + period is given by the following formula: + `duration (minutes) = (crash counter value - 2) x 5` + - If the crash counter value equals 2, 5 or 12, the platform sends a warning + e-mail to the application's collaborators. + - If the crash counter value reaches 13, which means the container keeps + crashing after 12 delayed restarts, the platform gives up. The container + is crashed and won't be restarted anymore, which means your application + may now be totally unavailable. + +### Fixing Runtime Errors + +Besides the measures taken by the platform, we strongly advise you to carefully +investigate the logs of your crashing application as soon as possible. Once +your fix is ready, push your updated code to Scalingo to trigger a new +deployment, hopefully resolving the issue. + +## Getting Notified When a Crash Occurs + +By default, the platform only notifies the application's collaborator(s) when +a recurrent crash occurs (i.e. when an early Runtime Error keeps occurring, or +when a Timeout Error occurs). + +You can modify this behavior by tweaking your +[Notifier's configuration]({% post_url platform/app/2000-01-01-notifiers %}). +The `app_crashed`, `app_crashed_repeated` and the `app_deploy` events can be +particularly worth considering. diff --git a/src/_posts/platform/getting-started/2000-01-01-common-deployment-errors.md b/src/_posts/platform/getting-started/2000-01-01-common-deployment-errors.md deleted file mode 100644 index c9b5e7a36..000000000 --- a/src/_posts/platform/getting-started/2000-01-01-common-deployment-errors.md +++ /dev/null @@ -1,206 +0,0 @@ ---- -title: Common Deployment Errors -modified_at: 2026-04-29 12:00:00 -index: 7 ---- - -## Unknown Technology - -When pushing your app to Scalingo, you might get the following error: - -```text -<-- Start deployment of [my-app] --> - ! We didn't find the type of technology your are using... - We're sorry this build is failing! - - Refer to the documentation to find out why: - https://doc.scalingo.com/deployment/unknown-technology - - If you can't find the issue in your application, - please send us an email at support@scalingo.com - - <3, - Scalingo - ! Error deploying the application - ! → Invalid return code from buildpack -``` - -There are two main solutions to this problem. - -### Project in a Subdirectory (Monorepo) - -Your project might be located in a subdirectory of your Git repository, which is common in monorepo setups. This is -supported, but note that Scalingo's deployment system looks at the repository root by default. - -You need to setup the `PROJECT_DIR` environment variable for your application. See our dedicated page on -[environment variables]({% post_url platform/app/2000-01-01-environment %}). - -You can find more information about monorepo deployment in our [dedicated guide]({% post_url platform/app/2000-01-01-monorepo %}). - -### Technology Detection - -To detect the technology used by your application, we iterate over the -technologies alphabetically. It means that if your project contains multiple -technologies, we will pick the first one detected. - -If you want to skip the detection phase and force the use of a specific -buildpack, add the environment variable `BUILDPACK_NAME` to your project. - -If you need to use multiple technologies, you can use the [multi-buildpacks]({% -post_url platform/deployment/buildpacks/2000-01-01-multi %}). - -You can also develop your own buildpack and add the environment variable -`BUILDPACK_URL` to have complete control on the detection and build phases. - -More information is available on [buildpacks]({% post_url -platform/deployment/buildpacks/2000-01-01-intro %}) or [multi-buildpacks]({% -post_url platform/deployment/buildpacks/2000-01-01-multi %}). - -Here is how we detect your technology: - -[Ruby]({% post_url languages/ruby/2000-01-01-start %}) - -A `Gemfile` should be present at the root of your repository. - -[Node.js]({% post_url languages/nodejs/2000-01-01-start %}) - -The file `package.json` should be present at the root of the project. - -[Meteor]({% post_url languages/meteorjs/2000-01-01-start %}) - -The directory `.meteor` should be present at the root of your project. - -[PHP]({% post_url languages/php/2000-01-01-start %}) - -You need to have either an `index.php` file or both `composer.json` and `composer.lock` files at the root of your project. - -[Python]({% post_url languages/python/2000-01-01-start %}) - -The file `Pipfile`, `requirements.txt` or `setup.py` must be present at the root of your project. - -[Java]({% post_url languages/java/2000-01-01-start %}) - -The file `pom.xml` should be present at the root of your project. - -[Scala]({% post_url languages/scala/2000-01-01-start %}) - -You need to have at least an `*.sbt` file or a `project/*.scala`/`.sbt/*.scala` file or a `project/build.properties` file. - -[Groovy]({% post_url languages/groovy/2000-01-01-start %}) - -The file `grails-app` must be at the root of your project. - -[Clojure]({% post_url languages/clojure/2000-01-01-start %}) - -The file `project.clj` must be at the root of your project. - -[Go]({% post_url languages/go/2000-01-01-start %}) - -You need to have at least one `*.go` file at the root of your project. -Then, we detect the Go language and install any dependency with your `Godeps` directory (see more about [Godeps](https://github.com/tools/godep)). - -## Git Submodule - -If your project repository uses Git submodules, please be aware that Scalingo -will not pull them. This Git feature is not supported on the platform for -different reasons. The main reason being that we currently have no way to -authenticate the `git pull` operation to a private Git repository when doing -the deployment. Actually Git submodules are often considered as a broken -feature of Git, that is why we do not encourage its usage or support it today. - -We recommend you to vendor a specific release of the code of the sub-git -repository in your main repository before pushing. - -## Build Errors - -When your application is deployed, the dependencies are gathered and are packaged -into an _application image_ - -### Invalid Return Code From Buildpack - -Your application image is built using a buildpack ([List of buildpacks]({% post_url platform/deployment/buildpacks/2000-01-01-intro %})). -If the buildpack exits with an error, it is probably linked to your project. You should -be able to see the content of the error in your console. Then adapt your code according to it. - -If you think the error comes from our buildpacks, feel free to contact us and we will fix -it as soon as we can. - -### Image Too Large - -The maximal size of an application image is __2 GiB__. If your assets, your -dependencies and the code of your application weigh more than this limit, -different solutions are available to lighten the image of your application: - -* Try to remove unused external dependencies or assets. -* Define a [.slugignore file]({% post_url platform/app/2000-01-01-slugignore %}) to exclude files from the - image. - -If you absolutely need all these data, please contact us at -[support@scalingo.com](mailto:support@scalingo.com). - -{% note %} - Why this quota? Besides being a security limit, this quota is also present to - preserve the PaaS user experience. A large image results in longer deployments, the - instantness aspect is lost. -{% endnote %} - -### Archive Too Large - -When deploying an application, the Scalingo build system downloads the source code as an archive. -The maximum archive size is limited to **300 MB**. - -If your archive exceeds this limit you will get the following error: -``` -Fail to fetch source code: fail to handle tgz: The archive is too heavy (more than 314572800 bytes) -``` - -{% note %} -The limit applies to the **uncompressed** archive. - -For example: given a **200 MB .tar.gz** archive, when the underlying **.tar** archive is larger than **300 MB**, -then you will encounter this limit. - -{% endnote %} - -If you need to deploy a larger archive, please contact us at -[support@scalingo.com](mailto:support@scalingo.com). - -## Start Errors - - -After creating the container image of your application, it is deployed -in our infrastructure. The following errors may happen if your application -is not configured correctly. - -If something wrong happens, you should first look at the logs of your app. In -most cases, all the information you need is displayed here. - -### Boot Timeout - -When started on our servers, your application has **60 seconds** to bind the -port defined by the environment variable `PORT`. After this delay, we consider -that your application is not able to boot and this error happens. - -**Common causes** - -* The server is not listening on the port defined by the environment variable - `PORT`. Then your application is running correctly but it is not reachable. - The application must also listen on `0.0.0.0` and not `127.0.0.1`. - -### Crash of the Application - -When your application starts, it may stop unexpectedly for various reasons -related to your project. - -**Common causes** - -* Syntax error and import error in your code. Make sure that your project is - working correctly locally before deploying it on our platform. If it - doesn't, it won't be better here. -* The database link is badly configured. If you are using our built-in database - addons, we create an environment variable with a name following this scheme: - `SCALINGO_{DB_TYPE}_URL`. Your application must use this value or you can - rename it to fit your needs. -* The way your application is starting is incorrect and it results in a crash. - To define or change how your application is started by the platform, use the - [Procfile file]({% post_url platform/app/2000-01-01-procfile %}). diff --git a/src/_posts/platform/getting-started/2000-01-01-first-steps.md b/src/_posts/platform/getting-started/2000-01-01-first-steps.md index 3e87c9fd1..ec7f29938 100644 --- a/src/_posts/platform/getting-started/2000-01-01-first-steps.md +++ b/src/_posts/platform/getting-started/2000-01-01-first-steps.md @@ -1,7 +1,7 @@ --- title: First Steps On Scalingo nav: First Steps -modified_at: 2023-12-22 00:00:00 +modified_at: 2026-04-30 00:00:00 tags: follow-the-light ssh index: 1 --- @@ -10,29 +10,28 @@ index: 1 ### Git -Deploying an application on Scalingo requires you to have Git installed. +Scalingo lets you deploy and run your code using Git. To deploy an application, +you need to have Git installed on your computer. -* Linux: Use your package manager to install it. (example: `apt-get install git`) -* macOS: If you've installed XCode, Git has been automatically installed. Otherwise, - install it from [Git official website](https://git-scm.com/download/mac) -* Windows: Install if from [Git official website](https://git-scm.com/download/windows) +* [Install git on Linux](https://git-scm.com/install/linux) +* [Install git on macOS](https://git-scm.com/install/mac) +* [Install git on Windows](https://git-scm.com/install/windows) ### SSH Key Setup -To identify that you are allowed to push to your application, you need to setup SSH -authentication. +To verify that you are allowed to push code to your application, Scalingo uses +SSH authentication. -* [Guide for Linux]({% post_url platform/getting-started/2000-01-01-setup-ssh-linux %}) -* [Guide for MacOS]({% post_url platform/getting-started/2000-01-01-setup-ssh-macos %}) -* [Guide for Windows]({% post_url platform/getting-started/2000-01-01-setup-ssh-windows %}) +* [Configure your SSH keys on Linux]({% post_url platform/getting-started/2000-01-01-setup-ssh-linux %}) +* [Configure your SSH keys on macOS]({% post_url platform/getting-started/2000-01-01-setup-ssh-macos %}) +* [Configure your SSH keys on Windows]({% post_url platform/getting-started/2000-01-01-setup-ssh-windows %}) -For any operating system, you need to copy the content of the public key to your account. +Once you have your own SSH key pair, add the content of the **public** key to your +account. -With our dashboard: +Using our dashboard: [https://dashboard.scalingo.com/account/keys](https://dashboard.scalingo.com/account/keys) -[https://dashboard.scalingo.com/account/keys](https://dashboard.scalingo.com/account/keys) - -With our command line client: +Using our [command line client]({% post_url tools/cli/2000-01-01-start %}): ```bash scalingo keys-add [name of the key] [path to the key] @@ -44,6 +43,9 @@ scalingo keys-add Laptop ~/.ssh/id_ed25519.pub ## Some Tutorials to Start With +Once Git and SSH are ready, follow a tutorial for your language or framework to +easily deploy your first application on Scalingo. +