Railpack doc

Author: KevyVo

docs/concepts/Railpack.md

@@ -0,0 +1,120 @@
+---
+title: Railpack
+description: Defang will use Railpack to make an OCI-Compliant container image for your project.
+sidebar_position: 500
+---
+
+# Railpack
+
+[Railpack](https://railpack.com/) is a tool for building container images from source code with minimal configuration. It is the successor to [Nixpacks](https://nixpacks.com/) and incorporates several lessons learned from running Nixpacks in production at [Railway](https://railway.com/) over the years.
+
+In Defang deployments, one of the most common points of failure is a missing or invalid Dockerfile that can’t produce OCI-compliant images. This is especially common when Dockerfile are generated by LLMs or created by users with limited Docker experience. Since integrating Railpack into Defang, if no Dockerfile is provided, we now automatically build a working image for you using Railpack.
+
+## How to trigger a Defang Railpack deployment
+
+When you run a Defang Railpack deployment you need 2 components:
+
+1. A working application
+2. A valid compose file
+
+Your compose file should not mention a Dockerfile.
+
+For example,
+
+```yaml
+# compose.yaml
+services:
+  app:
+    restart: unless-stopped
+    build:
+      context: .
+    deploy:
+      resources:
+        reservations:
+          cpus: "1.0"
+          memory: 512M
+    ports:
+      - mode: ingress
+        target: 3000
+        published: 3000
+```
+
+## Troubleshooting and tips
+
+If the deployment fails, here are some things you can try.
+
+### Railpack Detection
+
+To allow Railpack to generate a build plan for your project, please structure it to include the following files, or rename existing ones to be compatible.
+
+#### Node
+
+Your project will be detected as a Node.js application if a `package.json` file exists in the root directory.
+
+Here is an example of a Railpack ready NextJS project.
+Here is an example of a Railpack ready React Vite project.
+
+#### Python
+
+Your project will be detected as a Python application if any of these conditions are met:
+
+- A main.py file exists in the root directory (If your main.py is named anything else)
+- A requirements.txt file exists
+- A pyproject.toml file exists
+- A Pipfile exists
+
+Here is an example of a Railpack ready Flask project.
+Here is an example of a Railpack ready Django project.
+
+#### Go
+
+Your project will be detected as a Go application if any of these conditions are met:
+
+- A go.mod file exists in the root directory
+- A go.work file exists in the root directory (Go workspaces)
+- A main.go file exists in the root directory
+
+Here is an example of a Railpack ready Golang project.
+
+#### PHP
+
+Your project will be detected as a PHP application if any of these conditions are met:
+
+- An index.php file exists in the root directory
+- A composer.json file exists in the root directory
+
+#### Java
+
+Your project will be detected as a Java application if any of these conditions are met:
+
+- A gradlew (Gradle wrapper) file exists in the root directory (to create this, if you don’t have one, run gradle wrapper)
+- A pom.{xml,atom,clj,groovy,rb,scala,yaml,yml} file exists in the root directory
+
+#### Ruby
+
+Your project will be detected as a Ruby application if any of these conditions are met:
+
+- A Gemfile file is present
+
+#### Rust
+
+Your project will be detected as a Rust application if any of these conditions are met:
+
+- A Cargo.toml file is present
+
+#### Elixir
+
+Your project will be detected as a Elixir application if any of these conditions are met:
+
+- A mix.exs file exists in the root directory.
+
+#### Static Sites
+
+Railpack can automatically build and setup a server for static sites that require no build steps. The [Caddy](https://caddyserver.com/) server is used as the underlying web server.
+
+Your project will be automatically detected as a static site if any of these conditions are met:
+
+- A Staticfile configuration file exists in the root directory
+- An index.html file exists in the root directory
+- A public directory exists
+- The RAILPACK_STATIC_FILE_ROOT environment variable is set