diff --git a/src/docs/overview/advanced-concepts.md b/src/docs/overview/advanced-concepts.md index 65231470d..2cef4d06c 100644 --- a/src/docs/overview/advanced-concepts.md +++ b/src/docs/overview/advanced-concepts.md @@ -3,77 +3,82 @@ title: Advanced Usage description: A guide that outlines the advanced concepts of Railway. --- -This document outlines the more advanced concepts of Railway. It covers things like build and deploy options, networking, integrations, and observability. +There are a lot of advanced concepts of Railway that can help you build your applications better. This document will cover some of these concepts like build and deploy options, networking, observability, and other integrations. ## Build and Deploy Options -Out of the box, many defaults are applied to builds and deployments. However, there are several ways to tailor things to your project spec. +Railway applies many defaults to your build and deploy configurations that work fine for most scenarios. Changing these defaults could help tune Railway better to your use-case and make it easier on your team. ### Build Options -Railway uses Railpack to build and deploy your code with zero configuration. When your needs require adjustments to the defaults, we make it easy to configure things like install, build, and start commands. +Under the hood, Railway uses Railpack to package your code into a container image that we then deploy to our infrastructure, with zero configuration for most workloads. For advanced projects, you might need to configure some of these defaults. You can do this by going to your Service > Settings > Build, and underneath that, Deploy. Here are three things you might want to configure: + +- **Custom Build Command**: This is the command that will be ran to build your final application. Railpack will find the best command for this, usually `npm run build` for JS-based projects, `cargo build --release` for Rust projects, and more. If your application needs to trigger something else to build your project, customize that command here. +- [**Pre-Deploy Command**](https://docs.railway.com/guides/pre-deploy-command): These are one or more commands that will be ran before running the main start command. A common use for this is database migrations. If your application needs to run a command before starting your main application, put that in a Pre-Deploy Command. +- **Custom Start Command**: This is the command that will actually run your application. Defaulted as `npm run start` for JS-based applications. If you need to start your application in a way that's different than expected, change that here. ### Deploy Options -Deployments are created with some default options that can be overridden. Some of the options available are - +Some default options are applied when your application is deployed on Railway. They can change where your deployments are ran, how they are ran, and what happens to them while they're running. Here are some things you can change: -- **Replicas**: By default, your deployment will go out with a single instance. With replicas, you have the ability to scale up your deployment instances. -- **Deployment Region**: Deployments by default are pushed to your [preferred region](https://railway.com/workspace). -- **Scheduled Executions**: Your deployment will be run once by default. If the service is intended to be a scheduled task of sorts, you can create a cron schedule. -- **App Sleep**: Services are serverful and always-on. You can control this behavior, to spin down resources when they're not being used, by enabling App Sleep. +- [**Replicas**](https://docs.railway.com/reference/scaling#horizontal-scaling-with-replicas): By default, your deployment will go out with a single instance in your [preferred region](https://docs.railway.com/guides/optimize-performance#set-a-preferred-region). With replicas, you can deploy multiple instances of your application in one or more regions. The Railway network will load balance incoming requests between the available replicas and serve the ones closest to your users. +- **Deployment Region**: If you haven't configured any Replicas, your services will be deployed to the [preferred region](https://docs.railway.com/guides/optimize-performance#set-a-preferred-region) configured in your workspace. To change an individual service's region, go to Settings > Deploy > Regions. +- **Scheduled Executions**: If your deployment isn't a long-running service, like most web or backend services are, your deployment will be run once then exit. If the service is intended to be a repeated task, you can create a cron schedule under Settings > Deploy that will re-run your deployment according to the schedule. Each time it runs and exits successfully, it'll be marked as Completed. +- [**Serverless Deployments**](https://docs.railway.com/reference/app-sleeping): By default, services are long-running and will continue to run unless they error. You can configure your services to pause if no traffic is going to them, and start it back up once a request comes in. Sleeping services don't incur resource usage. While your service is starting back up, the requests will be queued and delivered to the service once its fully up and running. +- [**Healthchecks**](https://docs.railway.com/reference/healthchecks): By default, as soon as your deployment is launched, it's considered "healthy". You can configure an endpoint path under Deploy > Healthcheck Path that Railway will fetch once it deploys your service to ensure that your service actually started up before it removes the previous deployment. This lets Railway know when your services are fully healthy and ready to receive traffic, so it doesn't start serving requests to a service that hasn't fully started yet. ## Networking -Networking can be tricky and time-consuming. We wanted to provide the best-in-class experience when it came to wiring things up. There are two basic ways we accomplish this. +Constructing efficient networking setups yourself can be tricky and time-consuming to get right. Included in the Railway experience is fast networking that just works and can help you build more modular services. ### Private Networking -Private Networking is a feature within Railway that will open network communication through a private wireguard mesh only accessible to your Railway services within a project. +[Private Networking](https://docs.railway.com/guides/private-networking) is a feature that lets your services communicate to other running services within your project simply by its service name. Under Settings > Networking, you can configure the specific domain that is given to your service. You can provide this private networking domain name to your services with [Reference Variables](https://docs.railway.com/guides/variables#reference-variables). + +Private Networking domains are available with [Railway-provided Variables](https://docs.railway.com/guides/variables#railway-provided-variables) that you can [provide to your other services](https://docs.railway.com/guides/variables#referencing-a-shared-variable), elimiating the need to hard-code their values. -All projects have private networking enabled and services are assigned a DNS name under the `railway.internal` domain. This DNS name resolves to the internal IP addresses of the services in a project. +Under the hood, Railway connects your services together with a WireGuard mesh and a DNS resolver that is scoped to your project and environment. Services running inside of one project or environment aren't able to reach the services running in a different project. This also applies to environments within a project being unable to reach other environments. -### Railway-Provided Domains +### Railway-provided Domains -With the click of a button, Railway will expose your service to the internet and provide you with a domain. In order to make this work, you must configure your application appropriately to ensure we know the port it is listening on. Instructions for how to do this can be found in the [Public Networking guide](/guides/public-networking). +Railway provides a [customizable, Railway-branded domain](https://docs.railway.com/guides/public-networking#railway-provided-domain) for your service that you can connect to a port running on your service and instantly make it available to the public internet. These domains require no DNS configuration on your end, and are perfect if you don't have a custom domain of your own just yet but still want to access your application. -#### Custom Domains +### Custom Domains -If you have a custom domain, you can easily add it to your Railway service. +If you have a [custom domain](https://docs.railway.com/guides/public-networking#custom-domains) that you've bought from a domain registrar, you can connect this to your Railway service to serve your application under. Railway will walk you through the configuration of the required DNS records, alert you if the configuration is wrong, and automatically provision SSL certificates for you so you can serve your application with `https://`. -## Integration Tools +## Integrations -A CLI and an API are available to wire your Railway projects into any workflow. +Integrations let you interact with your Railway workspace outside of the Railway dashboard. ### CLI -The Railway Command Line Interface (CLI) lets you interact with your Railway project from the command line, allowing you to do things like: +The Railway CLI lets you interact with your Railway project from your local machine on the command line, allowing you to do things like: -- Trigger deployments programmatically. -- Run services locally using environment variables from your Railway project. -- Create new Railway projects from the Terminal. -- Deploy templates. +- Triggering deployments programmatically +- Run your services locally using configured environment variables from your Railway project +- Launch new Railway projects from the terminal +- Deploy templates ### Public API The Railway public API is built with GraphQL and is the same API that powers the Railway dashboard. Similar to the CLI, you can interact with your Railway project programmatically by communicating with the API. +### Webhooks + +Projects can also configure [Webhook URLs](https://docs.railway.com/guides/webhooks) that can receive a number of events that are triggered by your services and other things inside your project. Using these in tandem with the Railway API can make some powerful workflows that respond to the rest of your project. They can also be used to deliver critical alerts to your team's Slack workspaces. + ## Environments -Railway environments give you an isolated instance of all databases and services in a project. You can use them to +Railway environments are isolated instances of the services running in your production environment that let you iterate on your workspace without affecting your production workloads. You can: -- Have development environments for each team member that are identical to the production environment +- Have development environments for each team member that mirror your production environment - Have separate staging and production environments -Within a service and environment, you can specify which branch to auto-deploy to that environment when a change is merged. +Within a service and environment, you can specify which branch of your GitHub repository to deploy to that environment when a commit is pushed. ## Observability -Any build or deployment logs emitted to standard output or standard error `( eg. console.log(...))` are captured by Railway so you can view or search for it later. - -### Service Logs - -Logs for a specific service deployment are available from a service's view in your project, useful when debugging build or deployment failures. - -### Centralized Logs +Railway services and deployments will likely output logs to describe how they are being built, what they are doing while running, or errors during either of these. -Logs for all of the services in a project can be viewed together in our Observability tool within a project. This is useful for debugging more general problems that may span multiple services. +These logs, when sent to the standard output or standard error (like when using `console.log()`, `print()`, and `console.error()`) will be shown in the [Build and Deploy tabs](https://docs.railway.com/guides/logs#build--deploy-panel) (depending on where they originated) of each service and can be viewed in the [Observability](https://docs.railway.com/guides/logs#log-explorer) page of your project, from which you can view logs from all your services.