diff --git a/sites/friday/config/_default/config.yaml b/sites/friday/config/_default/config.yaml index 2a2106cc91..859ccf0d86 100644 --- a/sites/friday/config/_default/config.yaml +++ b/sites/friday/config/_default/config.yaml @@ -53,7 +53,7 @@ module: - source: "../platform/src" target: "content" excludeFiles: - + # - "add-services/*" - "add-services/network-storage.md" @@ -70,7 +70,7 @@ module: - "create-apps/flexible-resources.md" - "dedicated-gen-2/*" - + - "dedicated-gen-3/*" # - "define-routes/*" @@ -88,8 +88,8 @@ module: - "domains/security/web-application-firewall/fastly.md" - "domains/steps/custom-domains-preview-environments.md" - # - "environments/*" - - "environments/scalability.md" + - "environments/*" + #- "environments/scalability.md" # - "feedback/*" diff --git a/sites/friday/src/environments/_index.md b/sites/friday/src/environments/_index.md new file mode 100644 index 0000000000..897513fbb2 --- /dev/null +++ b/sites/friday/src/environments/_index.md @@ -0,0 +1,290 @@ +--- +title: "Manage {{% vendor/name %}} environments" +weight: -75 +layout: single +sidebarTitle: Manage environments +description: Learn what environments on {{% vendor/name %}} are and how to take advantage of them. +keywords: + - Git push options + - git push options +--- + +A {{% vendor/name %}} environment contains one instance of an app (or [group of apps](../create-apps/multi-app/_index.md)) +with all the services needed for it to run. + +Each project can include multiple environments, +often divided into [environment types](../administration/users.md#environment-type-roles). +If you have a live site, you have at least a production environment. +You can think of other environments as copies of your live site +where you can run tests without worrying about damaging anything in production. +Once you have completed your tests, +you can merge your changes so that they're instantly and seamlessly deployed to production. + +You can create environments for development, testing, staging, review, and so on. +To organize your environments, you can create [hierarchical relationships](#hierarchy). + +## Create environments + +You can create new environments in one of two ways: + +- Push a local branch through Git or a [source integration](../integrations/source/_index.md). + +- [Branch](/glossary.md#branch) existing environments using the [CLI](/administration/cli/_index.md) + or the [Console](../administration/web/_index.md). + +When you branch an environment, you might want to create exact replicas of it. +In this case, each new environment inherits all of the data and services from its parent environment. +This includes databases, network storage, queues, and routing configurations. + +You can create {{% vendor/name %}} environments on demand. +Each environment is tied to a Git branch. +If you use a source integration, +you can even have environments created automatically for your pull requests and branches. + +You can also have branches that aren't tied to a running instance of your application. +These are called [inactive environments](#environment-status). + +## Default environment + +Your default environment comes from your default branch and is a [production environment](../administration/users.md#environment-type-roles). +Your project must have a default environment, +but you can [name it as you want](./default-environment.md). + +If you subscribed to a production plan, this environment is your **live site**. +You might want to give it a [custom domain name](../domains/steps/_index.md). + +## Environment status + +Your environments can have one of two statuses: + +- [Active](/glossary.md#active-environment): + A deployed environment with services and data. + +- [Inactive](/glossary.md#inactive-environment): + An environment that isn't deployed and has no services or data, only code. + +You can see the status of your environments in the [Console](../administration/web/_index.md) or the [CLI](/administration/cli/_index.md). + +{{< codetabs >}} ++++ +title=In the Console ++++ + +When you open your project, inactive environments appear lighter in the environment list. +You also can't select them from the **Environment** dropdown menu. + +To check the status of an environment, +you can also open it and view its information panel. + +<---> ++++ +title=Using the CLI ++++ + +To check the status of all your environments, from your project directory run the `{{% vendor/cli %}} environments` command. + +{{< /codetabs >}} + +You can [change an environment's status](./deactivate-environment.md) at any time. + +## Organize your environments + +### Hierarchy + +![Environment hierarchy](/images/management-console/environments.png "0.5") + +In {{% vendor/name %}}, your environments are organized in a hierarchy featuring parent and child environments. + +When you [branch](/glossary.md#branch) an environment, +the parent of the new environment is the environment it was created from. +You can [change the environment's parent](./change-parent.md) after it's been created. + +When you push a branch through Git or a [source integration](../integrations/source/_index.md), +the parent environment of the new environment is your [default environment](#default-environment). +Alternatively, you can [change the environment's parent](./change-parent.md) after it's been created. + +Each child environment can [sync](/glossary.md#sync) code and/or data down from its parent +and [merge](/glossary.md#merge) code up to its parent. +You can use child environments for development, staging, and testing. + +### Workflows + +Since you can customize your [environment hierarchy](#hierarchy), you can create your own workflows. +You can decide which structure best fits your needs. + +#### Possible approaches + +You may want to take one of the following approaches when creating your workflows: + +- **Agile**: A child environment per sprint. + Each story in the sprint can have its own environment as a child of the sprint environment. + +- **Developer-centric**: One QA environment and a few preview environments + (*per developer*, *per task*, or similar). + +- **Testing**: An operational test environment, a user test environment, and a few unit test environments. + +- **Hotfix**: One environment for each bug, security issue, or hotfix that needs deployment. + +#### Example workflow + +Example Agile workflow: + +1. An admin [branches](/glossary.md#branch) the Live (default) environment to create a Sprint environment. + +2. The admin gives each developer permission to branch the Sprint environment to create new feature environments. + + ![Agile branches with Live as the top parent, Sprint 1 as a child, and Feature 1 and Feature 2 as children of Sprint](/images/workflow/branches.svg "0.2") + +3. Feature 1 is developed and work is reviewed by accessing the deployed Feature 1 environment. + +4. When the review is done, Feature 1 is [merged](/glossary.md#merge) into the Sprint environment. + + ![Feature 1 is merged into the Sprint 1 environment](/images/workflow/merge-feature.svg "0.25") + +5. The remaining features [sync](/glossary.md#sync) with the Sprint environment. + This ensures their working environment is up-to-date with the latest code. + + ![Features from the Sprint 1 environment are synced with the Feature 2 environment](/images/workflow/sync.svg "0.25") + +6. When the sprint is complete and all features merged into the Sprint environment, + the admin makes a backup of the live site. + +7. The admin merges the Sprint environment into the Live environment. + + ![Features from the Sprint 1 environment are merged into the Live environment](/images/workflow/merge-live.svg "0.2") + +8. The admin syncs the next sprint's environment with the Live environment + to repeat and continue the development process. + + ![Features from the Live environment are synced with the Sprint 2 environment](/images/workflow/sync-live.svg "0.2") + +### Naming conventions + +You can organize and work with your preview environments in many different ways. +It can help to introduce a convention for how you name and structure your environments. + +For each environment, choose a name that represents what the environment is for. +If you use Agile, for example, you can adopt a naming convention similar to the following: + +```text +Live + Sprint1 + Feature1 + Feature2 + Feature3 + Sprint2 + Feature1 + Feature2 +``` + +If you prefer splitting your environments per developer and having a specific environment for each task or ticket, +you can adopt a naming convention similar to the following: + +```text +Staging + Developer1 + Ticket-526 + Ticket-593 + Developer2 + Ticket-395 +``` + +## Paused environments + +[Preview environments](/glossary.md#preview-environment) are often used for a limited time and then abandoned. +To prevent unnecessary consumption of resources, +{{% vendor/name %}} automatically pauses preview environments ([of both development and staging types](/glossary.md#environment-type)) that haven't been redeployed in 14 days. + +You can also pause an environment manually at any time. + +### Pause an environment + +To pause an environment, follow these steps: + +{{< codetabs >}} + ++++ +title=Using the CLI ++++ + +Run the following command: + +```bash +{{% vendor/cli %}} environment:pause --project {{< variable "PROJECT_ID" >}} --environment {{< variable "ENVIRONMENT_NAME" >}} +``` + +<---> ++++ +title=In the Console ++++ + +1. Navigate to your project and click {{< icon settings >}} **Settings**. +2. Under **Environments**, select the environment you want to pause. +3. In the **Status** tab, click **Pause environment**. + +{{< /codetabs >}} + +### Resume a paused environment + +Pushing new code or redeploying a paused environment automatically resumes it. +You can also resume it manually at any time. + +{{< codetabs >}} + ++++ +title=Using the CLI ++++ + +Run the following command: + +```bash +{{% vendor/cli %}} environment:resume --project {{< variable "PROJECT_ID" >}} --environment {{< variable "ENVIRONMENT_NAME" >}} +``` + +<---> ++++ +title=In the Console ++++ + +1. Navigate to the paused environment. +2. In the Activity tab, click **Resume environment**. +3. In the **Resume environment** window, click **Resume**. + +{{< /codetabs >}} + +The environment is redeployed and becomes available for use again. + +## Push options + +Git provides push options to pass a string to the server (see [the official Git documentation](https://git-scm.com/docs/git-push#Documentation/git-push.txt--oltoptiongt)). + +{{% vendor/name %}} supports some of these push options, +which allows you to push changes to your environment and trigger the following actions at the same time: + +| Action | Command | +| ------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------- | +| Activate the environment | `git push {{% vendor/cli %}} -o "environment.status=active"` | +| Set a title for the environment | `git push {{% vendor/cli %}} -o "environment.title="` | +| Set the parent environment | `git push {{% vendor/cli %}} -o "environment.parent="` | +| Clone the data from the parent environment | `git push {{% vendor/cli %}} -o "environment.clone_parent_on_create=True"` | +| Disable the cloning of the data from the parent environment | `git push {{% vendor/cli %}} -o "environment.clone_parent_on_create=False"` | +| Set the environment type (`development`, `staging`, or `production`) | `git push {{% vendor/cli %}} -o "environment.type="` | +| Define a [resource initialization strategy](/manage-resources/_index.md#define-a-resource-initialization-strategy) (`Default`, `Manual`, `Minimum`, or `Parent`) | `git push {{% vendor/cli %}} -o "resources.init="` | + +If your remote location isn't named `{{% vendor/cli %}}`, +make sure you adjust the commands accordingly. + +{{< note >}} + +You can't use push options if you have a [source integration](/integrations/source/_index.md) set up. + +{{< /note >}} + +The following example shows how, through a single `push`, +you can activate your environment, set a title for it, +set a parent environment for it, and clone the data from its parent into it. + +```bash {location="Terminal"} +git push {{% vendor/cli %}} -o "environment.status=active" -o "environment.title=my-environment-title" -o "environment.parent=my-parent-environment" -o "environment.clone_parent_on_create=True" +``` diff --git a/sites/friday/src/environments/backup.md b/sites/friday/src/environments/backup.md new file mode 100644 index 0000000000..53e607a738 --- /dev/null +++ b/sites/friday/src/environments/backup.md @@ -0,0 +1,147 @@ +--- +title: Back up an environment +description: See how to protect yourself from potential data loss by backing up your environments so they can be restored later. +weight: -10 +--- + +When you're making changes to your apps, +you want to be sure those changes only improve things and don't make you lose any data. +You also want to have a disaster recovery plan in place. +Backups help you protect yourself against potential data loss. + +You might want to create backups of your live environment before merging a different environment into it +or each time you increase the storage space of your services. + +You also have regularly scheduled automated backups of your production environments to cover most cases. + +Note that you can only create backups and restore active environments. +To work with an [inactive environment](/glossary.md#inactive-environment), +first activate it. + +## How backup and restore works + +1. As an [admin user](../administration/users.md), you can do a backup of your environment. + This backup includes the complete data and code of the environment. + All persistent data from all running [services](../add-services/_index.md) + and any files stored on [mounts](../create-apps/app-reference.md#mounts) are included. + The backup is stored internally on {{% vendor/name %}}. + That is, the backup can be applied to environments on {{% vendor/name %}}, but it can't be downloaded. + If you need to download backups, instead [export your mount and service data](/learn/tutorials/exporting.md)). + +2. You restore your environment using the backup. + At this point, the data and code from the backup are restored to ensure a consistent state. + The latest code in your repository may have been modified such that it no longer works correctly with the old, restored data. + + {{< note theme="warning" title="Warning" >}} + + {{% vendor/name %}} does not modify your Git repository. Any further changes you make use the latest code in your repository. + + {{< /note >}} + +3. Depending on your needs, you can do the following: + + a) To use the code from the time of the backup as a baseline for future changes, + make sure you restore it yourself in your Git repository. + To do so, use Git commands such as `revert`. + + b) To use your latest code instead, just redeploy your environment or push a new change. + +## Backups and downtime + +By default, creating a manual backup causes a momentary pause in site availability so that all requests can complete. +This means the environment is backed up in a known consistent state. +The total interruption is usually only 15 to 30 seconds. +Any requests during that time are held temporarily, not dropped. + +To avoid this downtime, use [live backups](#live-backups). + +For consistent backups, create the backups during non-peak hours for your site. + +## Retention + +For information on how long backups are retained, see the [data retention policy](../security/data-retention.md). + +## Use automated backups + +{{< vendor/name >}} provides 1 automated backup a day for your production environment, +with a [2-day retention](/security/data-retention.md) (2 days worth of backups are retained at any given point). + +For more information on the backups {{< vendor/name >}} provides, +see the [{{< vendor/name >}} backup policy](/security/backups.md). + +Automated backups are always [live](#live-backups). + +## Live backups + +You can create backups without any downtime. +This means your environment is running and open to connections during the backup. + +Because the connections may come in during backup creation, live backups may have data inconsistencies among containers. +They may make restorations less reliable. +To avoid such issues, schedule [manual backups](#create-a-manual-backup) during non-peak hours, +when the short amount of downtime is least noticed. + +You can create a manual live backup on a Grid project: + +{{< codetabs >}} ++++ +title=Using the CLI ++++ + +Use the `--live` flag: + +```bash +{{% vendor/cli %}} backup:create --live +``` + +<---> ++++ +title=In the Console ++++ + +When [creating the backup](#create-a-manual-backup), select **Run live backup** in the last step. + +{{< /codetabs >}} + +## Create a manual backup + +{{< vendor/name >}} provides up to 2 manual backups of your production environment, +plus 2 manual backups you can use for your [preview environments](/glossary/_index.md). +For more information, see the [{{< vendor/name >}} backup policy](/security/backups.md). + +You can create a manual backup using the [CLI](../administration/cli/_index.md) or in the [Console](../administration/web/_index.md). + +{{< codetabs >}} ++++ +title=Using the CLI +highlight=bash ++++ +{{% vendor/cli %}} backup:create +<---> ++++ +title=In the Console ++++ + +1. Navigate to the environment you want to back up. +2. Click **Backups**. +3. Click {{< icon backup >}} **Backup**. +4. Click **Backup**. + +{{< /codetabs >}} + +### Automate manual backups + +You can also automate the process of creating manual backups through [cron jobs](../create-apps/app-reference.md#crons). +The cron job uses the CLI command to back up the environment. +It requires you to [set up the CLI on the environment with an API token](../administration/cli/api-tokens.md#authenticate-in-an-environment). + +Although this process is automated, +backups created in this way count as manual for the [backup schedule](#backup-schedule). +They don't affect the automated backups taken as part of the schedule. + +## Physical storage location + +Backups are stored as binary large objects separate from your environments. +This storage is replicated over multiple data centers in different locations +[within the region your project is hosted in](https://platform.sh/trust-center/security/data-security/). +This means that in the rare event a data center becomes unavailable, your backups are still available. diff --git a/sites/friday/src/environments/cancel-activity.md b/sites/friday/src/environments/cancel-activity.md new file mode 100644 index 0000000000..853c9a7218 --- /dev/null +++ b/sites/friday/src/environments/cancel-activity.md @@ -0,0 +1,51 @@ +--- +title: Cancel an activity +description: See how to cancel running or pending activities in an environment. +--- + +If you have a stuck activity or you pushed a change you know doesn't work, +you can cancel a running or pending activity on an environment. +This works for activities such as builds, cron jobs, and source operations. + +You can cancel activities using the [CLI](../administration/cli/_index.md) +or in the [Console](../administration/web/_index.md). + +{{< codetabs >}} ++++ +title=Using the CLI ++++ + +Run the following command: + +```bash +{{% vendor/cli %}} activity:cancel +``` + +If you have more than one running or pending activity, choose which activity to cancel. + +You can also cancel a specific activity by specifying its ID: + +```bash +{{% vendor/cli %}} activity:cancel {{< variable "ACTIVITY_ID" >}} +``` + +Get the ID from the [activity log](../increase-observability/logs/access-logs.md#activity-logs). + +<---> ++++ +title=In the Console ++++ + +1. Open the environment where you want to cancel an activity. +2. In the [activity log](../increase-observability/logs/access-logs.md#activity-logs), + click {{< icon more >}} **More** next to the activity you want to cancel. +3. Click **Cancel**. + +{{< /codetabs >}} + +## Non-cancellable activities + +An activity can finish in between when you load the Console and when you click **Cancel**. +For example, when the activity is a [source operation](../create-apps/source-operations.md) +and the related build hook has already completed. +In such cases, you get a message that the activity can't be cancelled. diff --git a/sites/friday/src/environments/change-parent.md b/sites/friday/src/environments/change-parent.md new file mode 100644 index 0000000000..76346e91fa --- /dev/null +++ b/sites/friday/src/environments/change-parent.md @@ -0,0 +1,57 @@ +--- +title: Change an environment's parent +sidebarTitle: Change parent +description: Learn how to change.a given environment's parent environment. +toc: false +--- + +All environments default to having another environment as their parent. +If you [branched](/glossary.md#branch) the environment from another, +its parent starts as the environment it was created from. +If you pushed a branch through Git or a [source integration](../integrations/source/_index.md), +the parent defaults to the default environment. + +To change the environment's parent, follow these steps: + +{{< codetabs >}} + ++++ +title=In the Console ++++ + +- Select the project where you want to change the parent. +- From the **Environment** menu, select the environment you want to change. +- Click {{< icon settings >}} **Settings**. +- In the row with the environment's name, click **Edit {{< icon chevron >}}**. +- Select a **Parent environment**. +- Click **Save**. + +<---> + ++++ +title=Using the CLI ++++ + +Run the following command: + +```bash +{{% vendor/cli %}} environment:info -e parent +``` + +So if you have the environment `new-feature` and want to change its parent to `main`, run the following: + +```bash +{{% vendor/cli %}} environment:info -e new-feature parent main +``` + +{{< /codetabs >}} + +If you're not using a [source integration](/integrations/source/_index.md), +you can also set a parent for your environment when pushing changes to it. +To do so, run the following command: + +```bash +git push -o "environment.parent={{< variable "PARENT_ENVIRONMENT_NAME" >}}" +``` + +Learn more about how to [trigger actions on `push`](/environments/_index.md#push-options). diff --git a/sites/friday/src/environments/deactivate-environment.md b/sites/friday/src/environments/deactivate-environment.md new file mode 100644 index 0000000000..9e136434b7 --- /dev/null +++ b/sites/friday/src/environments/deactivate-environment.md @@ -0,0 +1,105 @@ +--- +title: Deactivate an environment +description: See how to deactivate environments you aren't using. +--- + +If you have environments you aren't using, you may want to deactivate them to save resources for what you need. +To deactivate an environment, you need to be an admin for the project or the given environment. + +{{< note >}} + +Your default environment is protected. +It can't be deactivated through the Console or the CLI. +To change which environment is the default, see how to [rename the default branch](./default-environment.md). + +{{< /note >}} + +Deactivating the project results in the following: + +* The environment becomes [inactive](/glossary.md#inactive-environment). + Unless it's reactivated, it's no longer deployed and isn't accessible from the web or via SSH. +* All services running on this environment are deleted. +* All data specific to the environment is deleted. + If the environment is reactivated, it syncs data from its parent environment. + +## Deactivate an environment + +To deactivate an environment, follow these steps: + +{{< codetabs >}} + ++++ +title=In the Console ++++ + +- Select the project with an environment you want to deactivate. +- From the **Environment** menu, select the environment. +- Click {{< icon settings >}} **Settings**. +- In the row with **Status**, click **Edit {{< icon chevron >}}**. +- Select the checkbox to show you understand the consequences. +- Click **Deactivate & Delete Data**. +- Confirm your choice. + +<---> + ++++ +title=Using the CLI ++++ + +Run the following command: + +```bash +{{% vendor/cli %}} environment:deactivate {{< variable "ENVIRONMENT_NAME" >}} +``` + +{{< /codetabs >}} + +## Delete the branch + +Inactive environments still have branches in Git. +To delete the branch entirely, run the following command: + +```bash +git push origin --delete {{< variable "BRANCH_NAME" >}} +``` + +## Reactivate an environment + +Reactivating an environment [syncs](/glossary.md#sync) data from its parent environment. + +To reactivate an inactive environment, follow these steps: + +{{< codetabs >}} + ++++ +title=In the Console ++++ + +- Select the project with an environment you want to reactivate. +- From the **Environment** menu, select the environment. +- Click {{< icon settings >}} **Settings**. +- In the row with **Status**, click **Edit {{< icon chevron >}}**. +- Click **Activate**. + +<---> ++++ +title=Using the CLI ++++ + +Run the following command: + +```bash +{{% vendor/cli %}} environment:activate {{< variable "ENVIRONMENT_NAME" >}} +``` + +{{< /codetabs >}} + +If you're not using a [source integration](/integrations/source/_index.md), +you can also activate an environment when pushing changes to it. +To do so, run the following command: + +```bash +git push -o "environment.status=active" +``` + +Learn more about how to [trigger actions on `push`](/environments/_index.md#push-options). \ No newline at end of file diff --git a/sites/friday/src/environments/default-environment.md b/sites/friday/src/environments/default-environment.md new file mode 100644 index 0000000000..dbb28609d7 --- /dev/null +++ b/sites/friday/src/environments/default-environment.md @@ -0,0 +1,185 @@ +--- +title: Rename the default environment +description: See how to change the name of your default/production environment after creating a project. +multipleTabs: true +--- + +You can set the name of your default/production environment when creating a project. +To change it after project creation, follow the steps below. +For consistency, the steps are all given using the [CLI](../administration/cli/_index.md). + +The examples below are based off of changing the default environment from `old` to `main`. +Replace these names with what suits your situation. + +If your site is already live, +remember that deactivating an environment is a destructive operation that can result in data loss. +To minimize potential issues, take the following steps: + +- Switch the default environment during non-peak hours. +- Keep your data by taking a [backup of the `old` environment](../environments/backup.md) +- Reduce your DNS time-to-live (TTL) to a minimum. + +## Requirements + +If you have a domain set for your default environment, remove it before changing the default branch. +Otherwise you get an error that `default domain must be a valid project domain`. + +To change the default branch, you need to be an [admin for the project](../administration/users.md) + +## Note on source integrations + +The following steps depend of whether your project has a [source integration](../integrations/source/_index.md). + +If it doesn't, {{% vendor/name %}} is your primary remote repository for the project. +If it does, GitHub, GitLab, or BitBucket hosts your primary remote repository for the project. + +## 1. Create a `main` environment + +{{< codetabs >}} ++++ +title=Without a source integration ++++ + +In your local copy of your repository, create a new environment from `old` called `main`: + +```bash +{{% vendor/cli %}} environment:branch main old +``` + +<---> ++++ +title=With a source integration ++++ +In your local copy of the external repository, make sure your default branch is up to date: + +```bash +git checkout old && git pull origin old +``` + +Then create the `main` branch off of your default branch and push it to the remote repository: + +```bash +git checkout -b main +git push origin main +``` + +Source integrations include all branches, but don't activate the corresponding environments in {{% vendor/name %}}. +Activate the `main` environment by running the following command: + +```bash +{{% vendor/cli %}} environment:activate main +``` + +{{< /codetabs >}} + +## 2. Copy settings + +If you have variables or other settings specific to your default environment, add those to the `main` environment. + +For example, you may have variables for your production environment set to not be inheritable +(such as if you set them with `--inheritable=false` through the CLI). +These variables aren't added automatically to child environments and so you need to add them to the `main` environment manually. + +If you want the `main` environment to send emails, [turn on outgoing email](../development/email.md). + +## 3. Make `main` a top-level branch + +To have `main` be your default, it needs to not be a child of `old`. +Use the following command to remove its parent and make it a top-level branch: + +```bash +{{% vendor/cli %}} environment:info -e main parent - +``` + +## 4. Make `main` the parent for other environments + +{{< codetabs >}} ++++ +title=Without a source integration ++++ +You probably have other environments that are children of `old`. +For each environment, update its parent to `main`: + +```bash +{{% vendor/cli %}} environment:info -e parent main +``` + +<---> ++++ +title=With a source integration ++++ + +To preserve your data on {{% vendor/name %}}, +it's best to switch your work in progress to be based off of `main`. + +Close any open pull/merge requests and resubmit them against `main`. +If you want to continue working on branches after switching the default branch, +rebase them by running `git rebase --onto main `. +Once you resubmit a request, it appears under the `main` environment on {{% vendor/name %}}. + +{{< /codetabs >}} + +## 5. Deactivate the `old` branch + +To change your default branch, you first need to deactivate the existing default branch to remove protections. +Deactivate the `old` environment without deleting it by running the following CLI command: + +```bash +{{% vendor/cli %}} environment:delete --no-delete-branch old +``` + +## 6. Set `main` as the default branch + +{{< codetabs >}} ++++ +title=Without a source integration ++++ + +Once `old` has been deactivated, set the project's default branch to `main`: + +```bash +{{% vendor/cli %}} project:info default_branch main +``` + +<---> ++++ +title=With a source integration ++++ + +Once `old` has been deactivated, set the project's default branch in {{% vendor/name %}} to `main`: + +```bash +{{% vendor/cli %}} project:info default_branch main +``` + +Follow the instructions to change the default branch to `main` for your provider: + +- [GitHub](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-branches-in-your-repository/changing-the-default-branch) +- [GitLab](https://docs.gitlab.com/ee/user/project/repository/branches/default.html#change-the-default-branch-name-for-a-project) +- [BitBucket](https://community.atlassian.com/t5/Bitbucket-questions/How-to-change-MAIN-branch-in-BitBucket/qaq-p/977418) + +{{< /codetabs >}} + +## 7. Update DNS records + +Whether or not you're using a CDN, +if your site is live you have probably added a {{% vendor/name %}} address somewhere when configuring a [custom domain](../domains/steps/_index.md). +If you have a CDN, it's with the CDN provider. +If you don't have a CDN, it's probably a `CNAME` record. + +In either case, the setting probably has the old environment name as part of it. +Update the setting to use the new environment name. + +Verify that the new URL is correct by comparing it to the result from this command: + +```bash +{{% vendor/cli %}} environment:info edge_hostname +``` + +## 8. Optional: Delete the `old` environment + +If you no longer want the `old` environment, such as to stop accidental use, delete it completely: + +```bash +{{% vendor/cli %}} environment:delete --delete-branch old +``` diff --git a/sites/friday/src/environments/http-access-control.md b/sites/friday/src/environments/http-access-control.md new file mode 100644 index 0000000000..7ecbd5f088 --- /dev/null +++ b/sites/friday/src/environments/http-access-control.md @@ -0,0 +1,99 @@ +--- +title: Configure HTTP access control +description: Learn how to control access to.a given environment using HTTP methods. +keywords: + - basic authentication +--- + +When developing your site, you might want to hide your preview environments from outside viewers. +Or you may find you have performance issues from [excessive bot access](https://community.platform.sh/t/diagnosing-and-resolving-issues-with-excessive-bot-access/792). +You can control access either with a username and password or by allowing/denying specific IP addresses or networks. +This setting applies to the entire environment. + +The settings for a specific environment are inherited by all of its children. +So if you have a `staging` environment and you [branch environments from it](/glossary.md#branch), +all of the environments branched from it inherit the same authentication information. + +Changing access control triggers a new deploy of the current environment. +The changes don't propagate to child environments until they're [redeployed manually](../development/troubleshoot.md#force-a-redeploy). + +## Use a username and password + +You can set up one or more combinations of a username and password. +To add a username and password, follow these steps: + +{{< codetabs >}} + ++++ +title=In the Console ++++ + +- Select the project where you want to add login details. +- From the **Environment** menu, select an environment. +- Click {{< icon settings >}} **Settings**. +- In the row with **HTTP access control**, click **Edit {{< icon chevron >}}**. +- Click **+ Add Login**. +- Enter the username (login) and password into the given fields. +- Click **Save**. + +<---> ++++ +title=Using the CLI ++++ + +Run the following command: + +```bash +{{% vendor/cli %}} environment:http-access -e {{< variable "ENVIRONMENT_NAME" >}} --auth {{< variable "USERNAME" >}}:{{< variable "PASSWORD" >}} +``` + +For example, to add the username `name` with the password `12321` to the `test` environment, run: + +```bash +{{% vendor/cli %}} environment:http-access -e test --auth name:12321 +``` + +{{< /codetabs >}} + +## Filter IP addresses + +You can control access to environments by allowing or denying specific IP addresses or ranges of IP addresses. +The addresses should be in the [CIDR format](https://en.wikipedia.org/wiki/Classless_Inter-Domain_Routing). +Both`4.5.6.7` and `4.5.6.0/8` are accepted formats. + +Note that `allow` entries should come before `deny` entries in case they both match. + +For example, the following configuration allows only the IP `198.51.100.0` to access your website. + +```txt +198.51.100.0 allow +0.0.0.0/0 deny +``` + +To control access based on IP address, follow these steps: + +{{< codetabs >}} + ++++ +title=In the Console ++++ + +- Select the project where you want to control access. +- From the **Environment** menu, select the environment to control. +- Click {{< icon settings >}} **Settings**. +- In the row with **HTTP access control, click Edit {{< icon chevron >}}**. +- Enter the IP addresses or ranges into the **IP addresses** field. Put one address or range per line, followed by a space and then `allow` or `deny`. +- Click **Save**. + +<---> ++++ +title=Using the CLI ++++ + +Run the following command: + +```bash +{{% vendor/cli %}} environment:http-access -e {{< variable "ENVIRONMENT_NAME" >}} --access allow:{{< variable "IPS_TO_ALLOW" >}} --access deny:{{< variable "IPS_TO_DENY" >}} +``` + +{{< /codetabs >}} diff --git a/sites/friday/src/environments/restore.md b/sites/friday/src/environments/restore.md new file mode 100644 index 0000000000..72cd736bac --- /dev/null +++ b/sites/friday/src/environments/restore.md @@ -0,0 +1,115 @@ +--- +title: Restore an environment from a backup +sidebarTitle: Restore an environment +description: See how to restore an environment from a previous state. +weight: -10 +--- + +Once you have [backups of your environment](./backup.md), you can restore data from a previous point. + +To restore an environment, you need an [Admin role for that environment type](../administration/users.md). + +## 1. List available backups + +To restore an environment, first select one of the available backups: + +{{< codetabs >}} ++++ +title=Using the CLI ++++ + +Run the following command: + +```bash +{{% vendor/cli %}} backups +``` + +You get a response similar to the following: + +```bash +Backups on the project My Project (1234567abcdef), environment main (type: production): ++---------------------------+----------------------------+------------+ +| Created | Backup ID | Restorable | ++---------------------------+----------------------------+------------+ +| 2022-08-15T09:48:58+01:00 | 5ouvtgo4v75axijww7sqnftste | true | +| 2022-07-09T14:17:17+01:00 | 7jks7dru5xpx5p5id5wtypur2y | true | +| 2022-06-22T18:33:29+01:00 | f3jbyxlhtmalco67fmfoxs7n4m | true | ++---------------------------+----------------------------+------------+ +``` + +Select one of the backups marked as **Restorable** and copy its **Backup ID**. + +<---> ++++ +title=In the Console ++++ + +1. Navigate to the environment where you want to see backups. +2. Click **Backups**. + +Select one of the backups marked as having completed successfully {{< icon success >}}. + +{{< /codetabs >}} + +## 2. Restore from a backup + +To restore the backup you've selected, follow these steps: + +{{< codetabs >}} ++++ +title=Using the CLI ++++ + +1. Run the following command: + + ```bash + {{% vendor/cli %}} backup:restore {{< variable "BACKUP_ID" >}} + ``` + +2. Press `enter` to agree with the consequences and continue. + +<---> ++++ +title=In the Console ++++ + +1. Next to the backup you've selected, click **More** {{< icon more >}}. +2. Click **Restore**. +3. Read through the consequences and click **Yes, Restore**. + +{{< /codetabs >}} + +The data is restored and your backed-up environment is deployed. +This deployment uses the built app, including variables, from when the backup was taken. + +{{< note theme="warning" title="Warning" >}} + +The code is also initially restored, but {{% vendor/name %}} doesn't modify your Git repository. +So any future (re)deployments use the current Git repository to build the environment. + +To restore your code to its previous state when the backup was taken, +use Git commands such as [revert](https://git-scm.com/docs/git-revert). + +See [how backup and restore works on {{% vendor/name %}}](../environments/backup.md#how-backup-and-restore-works). + +{{< /note >}} + +## Restore to a different environment + +You can restore backups to a different environment than they were created on using the CLI: + +1. Switch to the branch where the backup was created. +2. To restore your backup to an existing environment, run the following command: + + ```bash + {{% vendor/cli %}} backup:restore --target={{% variable "TARGET_ENVIRONMENT_NAME" %}} {{% variable "BACKUP_ID" %}} + ``` + + If your target environment doesn't exist yet, you can create it by [branching an existing environment](/glossary.md#branch). + The new target environment will be an exact copy of the existing (parent) environment. + + To do so, use the `--branch-from` option to specify the parent of your new target environment: + + ```bash + {{% vendor/cli %}} backup:restore --target={{% variable "TARGET_ENVIRONMENT_NAME" %}} --branch-from={{% variable "PARENT_ENVIRONMENT_NAME" %}} {{% variable "BACKUP_ID" %}} + ``` \ No newline at end of file diff --git a/sites/friday/src/environments/search-engine-visibility.md b/sites/friday/src/environments/search-engine-visibility.md new file mode 100644 index 0000000000..c7ff88cc00 --- /dev/null +++ b/sites/friday/src/environments/search-engine-visibility.md @@ -0,0 +1,65 @@ +--- +title: Set an environment's visibility to search engines +sidebarTitle: Set search engine visibility +description: Learn how to change.a given environment's visbility to search engines. +--- + +When you have preview environments, +you don't want search engines indexing them and diluting the SEO of your production site. + +Search engine indexers are told to ignore all preview environments. +When you're ready to go live, give your production environment a [custom domain](../domains/steps/_index.md) +and then set it to be visible to search engines. + +To change your production environment's visibility to search engines, follow these steps: + +{{< codetabs >}} ++++ +title=Using the CLI ++++ + +To not restrict indexers on your production environment, run the following command: + +```bash +{{% vendor/cli %}} environment:info --environment {{< variable "PRODUCTION_ENVIRONMENT_NAME" >}} restrict_robots false +``` + +<---> ++++ +title=In the Console ++++ + +- Select the project where you want to change visibility. +- From the **Environment** menu, select your production environment. +- Click {{< icon settings >}} **Settings**. +- In the row with **Hide from search engines**, click **Edit {{< icon chevron >}}**. +- Select or clear the **Hide from search engines** checkbox. + +{{< /codetabs >}} + +{{% vendor/name %}} can't guarantee that indexers follow the instructions. +If you're concerned about access, set up [HTTP access control](./http-access-control.md). + +## How it's done + +When the **Hide from search engines** is activated, +search engines are turned away from environments by including a `X-Robots-Tag` header: + +```txt +X-Robots-Tag: noindex, nofollow +``` + +That tells search engine indexers to not index these sites and not traverse links from these sites. +This helps keep non-Production sites out of search engine indexes. + +You can choose whether to keep it on for production sites with custom domains. +It's automatically on for all `{{% vendor/cli %}}.site` domains. + +## Alternative method + +You can also send instructions to search engine indexers using a `robots.txt` file. +Your app can serve this as a static file from its disk or as a dynamic response from its `passthru`. +Control either with the [`location` section of your app configuration](../create-apps/app-reference.md#locations). + +If your `robots.txt` file includes instructions to ignore a page, +search engine indexers may ignore it even if you have configured {{% vendor/name %}} to not send the header. diff --git a/sites/platform/src/environments/_index.md b/sites/platform/src/environments/_index.md index 46e88e6fc3..83e439c42e 100644 --- a/sites/platform/src/environments/_index.md +++ b/sites/platform/src/environments/_index.md @@ -196,8 +196,6 @@ Staging To prevent unnecessary consumption of resources, {{% vendor/name %}} automatically pauses preview environments ([of both development and staging types](/glossary.md#environment-type)) that haven't been redeployed in 14 days. -{{% version/specific %}} - {{< note >}} If you're on a development plan, @@ -210,12 +208,6 @@ To prevent your production environment from being paused automatically, You can also pause an environment manually at any time. -<---> - -You can also pause an environment manually at any time. - -{{% /version/specific %}} - ### Pause an environment To pause an environment, follow these steps: @@ -280,31 +272,15 @@ Git provides push options to pass a string to the server (see [the official Git {{% vendor/name %}} supports some of these push options, which allows you to push changes to your environment and trigger the following actions at the same time: -{{% version/specific %}} - | Action | Command | | ------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------- | | Activate the environment | `git push {{% vendor/cli %}} -o "environment.status=active"` | | Set a title for the environment | `git push {{% vendor/cli %}} -o "environment.title="` | -| Set the parent environment | `git push {{% vendor/cli %}} -o "environment.parent="` | +| Set the parent environment | `git push {{% vendor/cli %}} -o "environment.parent="` | | Clone the data from the parent environment | `git push {{% vendor/cli %}} -o "environment.clone_parent_on_create=True"` | | Disable the cloning of the data from the parent environment | `git push {{% vendor/cli %}} -o "environment.clone_parent_on_create=False"` | | Set the environment type (`development`, `staging`, or `production`) | `git push {{% vendor/cli %}} -o "environment.type="` | -<---> - -| Action | Command | -| ------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------- | -| Activate the environment | `git push {{% vendor/cli %}} -o "environment.status=active"` | -| Set a title for the environment | `git push {{% vendor/cli %}} -o "environment.title="` | -| Set the parent environment | `git push {{% vendor/cli %}} -o "environment.parent="` | -| Clone the data from the parent environment | `git push {{% vendor/cli %}} -o "environment.clone_parent_on_create=True"` | -| Disable the cloning of the data from the parent environment | `git push {{% vendor/cli %}} -o "environment.clone_parent_on_create=False"` | -| Set the environment type (`development`, `staging`, or `production`) | `git push {{% vendor/cli %}} -o "environment.type="` | -| Define a [resource initialization strategy](/manage-resources/_index.md#define-a-resource-initialization-strategy) (`Default`, `Manual`, `Minimum`, or `Parent`) | `git push {{% vendor/cli %}} -o "resources.init="` | - -{{% /version/specific %}} - If your remote location isn't named `{{% vendor/cli %}}`, make sure you adjust the commands accordingly. @@ -320,4 +296,4 @@ set a parent environment for it, and clone the data from its parent into it. ```bash {location="Terminal"} git push {{% vendor/cli %}} -o "environment.status=active" -o "environment.title=my-environment-title" -o "environment.parent=my-parent-environment" -o "environment.clone_parent_on_create=True" -``` \ No newline at end of file +``` diff --git a/sites/platform/src/environments/backup.md b/sites/platform/src/environments/backup.md index 0a599b373c..5f1488bb3d 100644 --- a/sites/platform/src/environments/backup.md +++ b/sites/platform/src/environments/backup.md @@ -61,7 +61,6 @@ For consistent backups, create the backups during non-peak hours for your site. For information on how long backups are retained, see the [data retention policy](../security/data-retention.md). -{{% version/only "1" %}} ## Backup schedule Backups for Dedicated environments have a [specific frequency](../dedicated-gen-2/overview/backups.md). @@ -100,12 +99,9 @@ To upgrade to the higher schedule, follow these steps: 6. Click **Save**. To downgrade to the lower schedule, [contact support](/learn/overview/get-support.md). -{{% /version/only %}} ## Use automated backups -{{% version/specific %}} - For Dedicated environments, see more about [backups of Dedicated environments](../dedicated-gen-2/overview/backups.md). For Grid environments, automated backups are taken for Production environments at least once every day. @@ -114,15 +110,6 @@ The exact number of backups depends on your [backup schedule](#backup-schedule). Daily backups are taken at around 4:00 every day based on the [project timezone](../projects/change-project-timezone.md). The time for 6-hourly backups is based on the daily backup. -<---> - -{{< vendor/name >}} provides 1 automated backup a day for your production environment, -with a [2-day retention](/security/data-retention.md) (2 days worth of backups are retained at any given point). - -For more information on the backups {{< vendor/name >}} provides, -see the [{{< vendor/name >}} backup policy](/security/backups.md). -{{< /version/specific >}} - Automated backups are always [live](#live-backups). ## Live backups @@ -135,11 +122,8 @@ They may make restorations less reliable. To avoid such issues, schedule [manual backups](#create-a-manual-backup) during non-peak hours, when the short amount of downtime is least noticed. -{{% version/only "1" %}} - Automated backups are always live, including those taken on [{{% names/dedicated-gen-3 %}}](../dedicated-gen-3/_index.md) and [{{% names/dedicated-gen-2 %}}](../dedicated-gen-2/overview/_index.md) environments. -{{% /version/only %}} You can create a manual live backup on a Grid project: @@ -165,12 +149,6 @@ When [creating the backup](#create-a-manual-backup), select **Run live backup** ## Create a manual backup -{{% version/only "2" %}} -{{< vendor/name >}} provides up to 2 manual backups of your production environment, -plus 2 manual backups you can use for your [preview environments](/glossary/_index.md). -For more information, see the [{{< vendor/name >}} backup policy](/security/backups.md). -{{% /version/only %}} - You can create a manual backup using the [CLI](../administration/cli/_index.md) or in the [Console](../administration/web/_index.md). {{< codetabs >}}