diff --git a/src/data/sidebar.ts b/src/data/sidebar.ts index dbcbf92c9..12acde6a2 100644 --- a/src/data/sidebar.ts +++ b/src/data/sidebar.ts @@ -35,6 +35,7 @@ export const sidebarContent: ISidebarContent = [ subTitle: makePage("Foundations", "guides"), pages: [ makePage("Projects", "guides"), + makePage("Staged Changes", "guides"), makePage("Services", "guides"), makePage("Variables", "guides"), makePage("Volumes", "guides"), diff --git a/src/docs/guides/environments.md b/src/docs/guides/environments.md index 66e7419bd..1f9a3c403 100644 --- a/src/docs/guides/environments.md +++ b/src/docs/guides/environments.md @@ -2,18 +2,41 @@ title: Using Environments --- -Railway supports complex development workflows through environments, giving you isolated instances of all databases and services in a project. +Railway supports complex development workflows through environments, giving you isolated instances of all services in a project. ## Create an Environment -Create an environment under Settings > Environments. +1. Select `+ New Environment` from the environment drop down in the top navigation. You can also go to Settings > Environments. +2. Choose which type of environment to create - + - **Duplicate Environment** creates a copy of the selected environment, including services, variables, and configuration. + + When the duplicate environment is created, all services and their configuration will be staged for deployment. + *You must review and approve the [staged changes](/guides/staged-changes) before the services deploy.* -When you create an environment, Railway will provision the same services in the new environment as the `production` environment. + - **Empty Environment** creates an empty environment with no services. -Screenshot of Environments Page + width={1108} height={770} quality={100} /> + +### Caveats + +- Networking changes are not yet staged and are applied immediately. +- Adding databases or templates will only affect the current environment. However, they do not yet create a commit in the history. + ## Enable PR Environments @@ -31,97 +54,8 @@ When enabled, a temporary environment is spun up to support the Pull Request dep Railway will not deploy a PR branch from a user who is not in your team or invited to your project without their associated GitHub account. -## Forking and merging environments - -Environments in Railway can be forked and merged. Changes in a forked environment are not propagated automatically to the parent environment or any other environment. - -### Fork an environment - -Fork an environment from the environment selector dropdown in the navigation bar. Alternatively you can fork an environment in the Environments section in the project settings. - -### Merge changes from a forked environment - -In Railway's UI you'll see a dock widget at the bottom of the project canvas when a forked environment is active. - -Screenshot of Merge Widget - -Clicking on it will reveal a side panel with a list of changesets made into the active environment that haven't been propagated yet to the parent environment. - -Screenshot of Merge Panel - -Select which changes you want to propagate to the parent environment and click `Merge` to apply the changes. Note that you can override values if you do not want to apply them to the parent environment. - -At this moment only changes in environment variables can be merged, but we are working on adding support for any other changes made to a service. - -## Staged Changes - - - -Staged changes is a feature that touches many parts of the Railway dashboard. At its core, it allows you to group multiple changes together and deploy them all at once. Other changes include - -- A updated settings page for both services and volumes -- All changes are now scoped to an environment -- A new activity feed that shows all the changes made - -You can enable staged changes for your account on the [feature flags](https://railway.app/account/feature-flags) page. - -### Making changes - -When you make a change to a service or volume, that change will be staged. - -1. The number of staged changes will be displayed in a banner in the top left corner of the canvas -2. Staged changes will appear as purple in the UI - -Staged changes on Railway canvas - -You can discard the changes by opening up the 3-dot menu in the banner. - -Clicking "Details" will open up a modal that shows all the changes that have been staged. You can optionally add a commit message that will appear in the activity feed. - -Staged changes on Railway canvas - -Clicking "Deploy" will deploy all of the changes at once. Any services that are affected will be redeployed. - -### Isolated environments - -When staged changes are enabled, all changes are scoped to an environment. This means that you can make changes to an environment without affecting other environments. - -### Activity feed - -The activity feed shows all the changes that have been made to a project. This includes changes to services and volumes. You can click on a change to see everything that was committed. - -Commit activity feed - -### Bringing in services from other environments - -Since adding new volumes and services is now scoped to the current environment, you may want to _import_ a service added from another environment. To do this you can open up the new service menu. Any service that is not currently in the current environment will appear at the top of the list. When selected you can choose if you want to import the configuration from another environment, or start from scratch. - -Importing service from another environment - -### Caveats - -- Networking changes are not yet staged and are applied immediately. -- Adding databases or templates will only affect the current environment. However, they do not yet create a commit in the history. -- When staged changes are enabled, forking environments is disabled. Staging changes is our long-term vision for environments which will incorporate the best parts of forking environments. However, at the moment the two features are incompatible. +## Forked Environments -### Feedback +As of January 2024, forked environments have been deprecated in favor of Isolated Environments with the ability to Sync. -Staged changes is big change to the Railway dashboard. We'd love to hear your [feedback on the feature](https://community.railway.app/discuss/thread/staged-changes-720f7804). +Any environments forked prior to this change will remain, however, you must adopt the [Sync Environments](#sync-environments) flow, in order to merge changes into your base environment. diff --git a/src/docs/guides/projects.md b/src/docs/guides/projects.md index ed3996210..6dc0d5c5b 100644 --- a/src/docs/guides/projects.md +++ b/src/docs/guides/projects.md @@ -61,6 +61,15 @@ width={411} height={253} quality={80} /> The transferee receives an email with the current owner requesting to transfer the project to the user. Once that user accepts the transfer, they become the new owner of the project. +## Viewing Recent Activity + +The activity feed shows all the changes that have been made to a project. This includes changes to services and volumes. You can click on a change to see everything that was committed. + +Commit activity feed + ## Updating Project Visibility Projects are private by default and only accessible to members of the project. However, you can make your projects public to share in a read-only state by changing the visibility in project settings - diff --git a/src/docs/guides/services.md b/src/docs/guides/services.md index 781cd9e95..22a13c208 100644 --- a/src/docs/guides/services.md +++ b/src/docs/guides/services.md @@ -4,6 +4,8 @@ title: Managing Services A Railway Service is a deployment target for your application. +*As you create and manage your services, your changes will be collected in a set of [staged changes](/guides/staged-changes) that you must review and deploy, in order to apply them.* + ## Creating A Service Create a service by clicking the `New` button in the top right corner of your project canvas, or by typing new service from the **command palette**, accessible via `CMD + K` (Mac) or `Ctrl + K`(Windows). diff --git a/src/docs/guides/staged-changes.md b/src/docs/guides/staged-changes.md new file mode 100644 index 000000000..a851db2af --- /dev/null +++ b/src/docs/guides/staged-changes.md @@ -0,0 +1,34 @@ +--- +title: Staged Changes +--- + +Changes made in your Railway project, like adding, removing, or making changes to components, will be staged in a changeset for you to review and apply. + +It is important to be familiar with this flow as you explore the upcoming guides. + +### What to Expect + +As you create or update components within your project - + +1. The number of staged changes will be displayed in a banner on the canvas +2. Staged changes will appear as purple in the UI + +Staged changes on Railway canvas + +### Review and Deploy Changes + +To review the staged changes, click the "Details" button in the banner. Here, you will see a diff of old and new values. You can discard a change by clicking the "x" to the right of the change. + +You can optionally add a commit message that will appear in the [activity feed](/guides/projects#viewing-recent-activity). + +Staged changes on Railway canvas + +Clicking "Deploy" will deploy all of the changes at once. Any services that are affected will be redeployed. + +Holding the "Alt" key while clicking the "Deploy" button allows you to commit the changes without triggering a redeploy. \ No newline at end of file diff --git a/src/docs/guides/variables.md b/src/docs/guides/variables.md index 6b4e88bc4..1b7bb5bf9 100644 --- a/src/docs/guides/variables.md +++ b/src/docs/guides/variables.md @@ -13,6 +13,8 @@ When defined, they are made available to your application as environment variabl In Railway, there is also a notion of configuration variables which allow you to control the behavior of the platform. +*Adding, updating, or removing variables, results in a set of [staged changes](/guides/staged-changes) that you must review and deploy, in order to apply them.* + ## Service variables Variables scoped to individual services can be defined by navigating to a service's "Variables" tab. diff --git a/src/docs/reference/environments.md b/src/docs/reference/environments.md index d11318643..5aaed2961 100644 --- a/src/docs/reference/environments.md +++ b/src/docs/reference/environments.md @@ -12,18 +12,18 @@ All projects in Railway are created with a `production` environment by default. #### Persistent Environments -Persistent environments contain the same services as the production environment, but not the same variables. These environments are intended to persist but remain isolated from production with regard to their configuration. For example, a `staging` environment that is configured to auto-deploy from a `staging` branch. +Persistent environments are intended to persist but remain isolated from production with regard to their configuration. -#### Forked Environments - -Forked environments contain the same services AND variables of the original environment. - -A key difference between forked and persistent environments are changesets. Changes in a forked environment are stored in a changeset to be reviewed and merged into the original environment. +For example, it is a common pattern to maintain a `staging` environment that is configured to auto-deploy from a `staging` branch and with variables relevant to `staging`. #### PR Environments [PR Environments](/guides/environments#enable-pr-environments) are temporary. They are created when a Pull Request is opened on a branch and are deleted as soon as the PR is merged or closed. +## Environment Isolation + +All changes made to a service are scoped to a single environment. This means that you can make changes to a service in an environment without affecting other environments. + ## Use Cases Environments are generally used for isolating changes from the production environment, to iterate and test before pushing to production.