Merge pull request #262 from DefangLabs/kevin/railpack

Railpack doc

Author: lionello

docs/concepts/railpack.md

@@ -0,0 +1,146 @@
+---
+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 issues faced by users 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
+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 restructure or rename your existing project files to be Railpack-compatible, as described for each framework below.
+
+#### [Node](https://railpack.com/languages/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 [React Vite project](https://github.com/DefangLabs/samples/tree/main/samples/react-vite-railpack)
+- A Railpack-ready [NextJS project](https://github.com/DefangLabs/samples/tree/main/samples/nextjs-railpack)
+
+#### [Python](https://railpack.com/languages/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 [Django project](https://github.com/DefangLabs/samples/tree/main/samples/django-railpack)
+- A Railpack-ready [Flask project](https://github.com/DefangLabs/samples/tree/main/samples/flask-railpack)
+
+#### [Go](https://railpack.com/languages/golang)
+
+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](https://github.com/DefangLabs/samples/tree/main/samples/golang-http-form-railpack)
+
+#### [PHP](https://railpack.com/languages/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](https://railpack.com/languages/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](https://railpack.com/languages/ruby)
+
+Your project will be detected as a Ruby application if any of these conditions are met:
+
+- A Gemfile file is present
+
+#### [Rust](https://railpack.com/languages/rust)
+
+Your project will be detected as a Rust application if any of these conditions are met:
+
+- A Cargo.toml file is present
+
+#### [Elixir](https://railpack.com/languages/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](https://railpack.com/languages/staticfile)
+
+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
+
+Static sites are served using the Caddy web server and you need to have the environment variable `PORT` exposed like this in the Compose file to map to the correct port:
+
+```
+services:
+  app:
+    restart: "unless-stopped"
+    build:
+      context: ./app
+    # This is the port you need to add
+    environment:
+      PORT: 5173 # <--- PORT
+    ports:
+      - target: 5173
+        published: 5173
+        mode: ingress
+    deploy:
+      resources:
+        reservations:
+          memory: 512M
+```