diff --git a/src/docs/guides/environments.md b/src/docs/guides/environments.md index 66e7419bd..221978164 100644 --- a/src/docs/guides/environments.md +++ b/src/docs/guides/environments.md @@ -2,91 +2,38 @@ 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](#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. - -Screenshot of Environments Page - -## Enable PR Environments - -Railway can spin up a temporary environment whenever you open a Pull Request. To enable PR environments, go to your Project Settings -> Environments tab. - - - -When enabled, a temporary environment is spun up to support the Pull Request deploy. These environments are deleted as soon as these PRs are merged or closed. - -### How come my GitHub PR won't deploy? - -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. + - **Empty Environment** creates an empty environment with no services. ## 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 +3. Each service card that has received a change will be tagged "Edited" Staged changes on Railway canvas -You can discard the changes by opening up the 3-dot menu in the banner. +### Review and Deploy Changes -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. +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 +- 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. -### Bringing in services from other environments +## Enable PR 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. +Railway can spin up a temporary environment whenever you open a Pull Request. To enable PR environments, go to your Project Settings -> Environments tab. -Importing service from another environment + -### Caveats +When enabled, a temporary environment is spun up to support the Pull Request deploy. These environments are deleted as soon as these PRs are merged or closed. -- 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. +### How come my GitHub PR won't deploy? + +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. + +## 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). +If you still have a forked environment, it will remain in your project until you merge it. 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/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.