🔀 Merge pull request #2649 access-your-site

📝 Rework access site page and add file transfer page

docs/src/development/access-site.md

@@ -1,18 +1,12 @@
 ---
-title: "Accessing your site"
+title: "Access your site"
 weight: 6
 description: |
-  Once you have an environment running, there are many ways to access it to perform needed tasks. The most straightforward way is to view it in a web browser; the available URLs are shown in the Platform.sh Console and on the command line after every Git push.
+  Find the URLs you can use to access your site via a web browser.
 ---
 
-{{% description %}}
-
-By design, the only way to deploy new code is to push to the corresponding branch.
-That ensures a consistent, repeatable, auditable application instance at all times.
-
-## Visiting the site on the web
-
-To find the URLs to access your site, follow these steps:
+Once you have an environment running, you can view it in a web browser. 
+To find which URLs you can use to access your site, follow these steps:
 
 {{< codetabs >}}
 
@@ -22,9 +16,11 @@ file=none
 highlight=false
 ---
 
-- Select the project where you want to find the URLs.
-- From the **Environment** menu, select an environment.
-- Click **URLs**.
+1. Select the project whose URLs you want to find.
+2. From the **Environment** menu, select an environment.
+3. Click **URLs**.
+
+Copy and paste any of these URLs into a web browser and access your site.
 
 <--->
 
@@ -34,143 +30,17 @@ file=none
 highlight=false
 ---
 
-Run the following command:
-
-```bash
-platform url --project <PROJECT_ID>
-```
-
-{{< /codetabs >}}
-
-Generally there are two URLs created per route in your `routes.yaml` file:
-One HTTPS and one HTTP route that just redirects to HTTPS.
-If you're using the `{all}` placeholder in your `routes.yaml` file,
-then there are more, depending on how many domains you have configured in your project.
-
-## Access your app with SSH
-
-See how to [access apps with SSH](./ssh/_index.md#connect-to-apps)
-
-The application container is a fully working Linux environment using the `bash` shell.
-Most of the system consists of a read-only file system so you can't edit code, but the full system is available to read.
-Any file [mounts](../create-apps/app-reference.md#mounts)
-you have declared in your [app configuration](../create-apps/_index.md) are writable.
-
-Additionally, you are logged in as the same user that the web server runs as.
-So you don't have to worry about editing a file from the command line and from your application
-resulting in inconsistent and broken file ownership and permissions.
-
-## Uploading and downloading files
-
-The writable static files in an application (including uploads and temporary and private files)
-are stored in [mounts](../create-apps/app-reference.md#mounts).
-
-The Platform.sh CLI can list mounts inside an application:
-
-```bash
-$ platform mounts
-Mounts in the app drupal (environment main):
-+-------------------------+----------------------+
-| Path                    | Definition           |
-+-------------------------+----------------------+
-| web/sites/default/files | shared:files/files   |
-| private                 | shared:files/private |
-| tmp                     | shared:files/tmp     |
-+-------------------------+----------------------+
-```
-
-The CLI also helps in transferring files to and from a mount using the `mount:upload` and `mount:download` commands.
-These commands use the rsync utility, which in turn uses SSH.
-
-For example, to download files from the 'private' mount:
-
-```bash
-$ platform mount:download --mount private --target ./private
-
-This will add, replace, and delete files in the local directory 'private'.
-
-Are you sure you want to continue? [Y/n]
-Downloading files from the remote mount /app/private to /Users/alice/Projects/foo/private
-  receiving file list ...
- done
+1. Run the following command:
 
-  sent 16 bytes  received 3.73K bytes  2.50K bytes/sec
-  total size is 1.77M  speedup is 471.78
-  time: 0.91s
-The download completed successfully.
-```
+   <div class="highlight">
+     <pre class="chroma"><code class="language-bash" data-lang="bash">platform url --project {{< variable "PROJECT_ID" >}} --environment {{< variable "ENVIRONMENT_NAME" >}}</code></pre>
+   </div>
 
-Uploading files to a mount is similar:
+2. Select the URL to open in a browser.
 
-```bash
-$ platform mount:upload --mount private --source ./private
-
-This will add, replace, and delete files in the remote mount 'private'.
-
-Are you sure you want to continue? [Y/n]
-Uploading files from /Users/alice/Projects/foo/private to the remote mount /app/private
-  building file list ...
- done
-
-  sent 2.35K bytes  received 20 bytes  1.58K bytes/sec
-  total size is 1.77M  speedup is 745.09
-  time: 0.72s
-The upload completed successfully.
-```
-
-## Using SSH clients
-
-Many applications and protocols run on top of SSH,
-including the SSH File Transfer Protocol (SFTP), secure copy (scp), and rsync.
-You need to set up [SSH keys](./ssh/ssh-keys.md) and let your client access the private key.
-
-Then [get the SSH connection details](./ssh/_index.md#get-ssh-connection-details) for the environment.
-Enter the host and username into your client.
-
-### SFTP
-
-SFTP is another way to upload and download files to and from a remote environment.
-There are many SFTP clients available for every operating system.
-
-### scp
-
-scp is a basic command-line utility to copy files to and from a remote environment.
-
-For example, to download a `diagram.png` file from the `web/uploads` directory (relative to the [app root](../create-apps/app-reference.md#root-directory)),
-run the following command (replacing `<PROJECT_ID>` and `<ENVIRONMENT_NAME>` with appropriate values):
-
-```bash
-scp "$(platform ssh --pipe -p <PROJECT_ID> -e <ENVIRONMENT_NAME>)":web/uploads/diagram.png .
-```
-
-The file is copied to the current local directory.
-
-To copy files from your local directory to the Platform.sh environment, reverse the order of the parameters:
-
-```bash
-scp diagram.png "$(platform ssh --pipe -p <PROJECT_ID> -e <ENVIRONMENT_NAME>)":web/uploads
-```
-
-Consult the [scp documentation](https://www.man7.org/linux/man-pages/man1/scp.1.html) for other options.
-
-### rsync
-
-For copying files to and from a remote environment, rsync is the best tool available.
-It's a little more complicated to use than scp, but it can also be a lot more efficient,
-especially if you are only updating files that are already partially copied.
-
-The CLI [`mount:upload` and `mount:download` commands](#uploading-and-downloading-files)
-are helpful wrappers around rsync that make it a little easier to use.
-
-You can also use rsync on its own.
-For example, to copy all files in the `web/uploads` directory on the remote environment to the local `uploads` directory,
-run the following command (replacing `<PROJECT_ID>` and `<ENVIRONMENT_NAME>` with appropriate values):
+{{< /codetabs >}}
 
-```bash
-rsync -az "$(platform ssh --pipe -p <PROJECT_ID> -e <ENVIRONMENT_NAME>)":web/uploads/ ./uploads/
-```
+For more information about URLs in your project and how you can control access to your web applications, 
+see how to [define routes](../define-routes/).
 
-Note that rsync is very sensitive about trailing `/` characters.
-Consult the [rsync documentation](https://man7.org/linux/man-pages/man1/rsync.1.html) for more details.
 
-See the guides on [migrating](../tutorials/migrating.md) and [exporting](../tutorials/exporting.md) for more examples using rsync.

docs/src/development/email.md

@@ -1,6 +1,6 @@
 ---
 title: Send email
-weight: 8
+weight: 9
 sidebarTitle: Email
 description: Send email from your Platform.sh environments.
 ---

docs/src/development/file-transfer.md

@@ -0,0 +1,151 @@
+---
+title: "Transfer files to and from your app"
+weight: 7
+sidebarTitle: Transfer files
+---
+
+After your app is built, its file system is read-only.
+This means that the only way you can edit your app's code is through Git.
+
+However, you can transfer files to and from your built app without using Git.
+To do so, you need to configure mounts or use an SSH client.
+
+[Mounts](../create-apps/app-reference.md#mounts) let you set up directories that remain writable after the build is complete.
+You can then transfer files directly to and from mounts inside your app
+with a single command via the [Platform.sh CLI](../administration/cli/_index.md).
+
+Alternatively, you can transfer files to and from your built app using an SSH client 
+such as `scp` or `rsync`.
+
+## Transfer files using the CLI
+
+### View the mounts inside your app
+
+Before you start transferring files, 
+you may want to view a list of all the mounts inside your app. 
+To do so, run the following command:
+
+```bash
+$ platform mounts --project {{< variable "PROJECT_ID" >}} --environment {{< variable "ENVIRONMENT_NAME" >}}
+```
+
+The output is similar to the following:
+
+```bash
+Mounts on [email protected]:
++-------------------------+----------------------+
+| Mount path              | Definition           |
++-------------------------+----------------------+
+| web/sites/default/files | source: local        |
+|                         | source_path: files   |
+| private                 | source: local        |
+|                         | source_path: private |
+| tmp                     | source: local        |
+|                         | source_path: temp    |
++-------------------------+----------------------+
+```
+
+### Transfer a file to a mount
+
+To transfer a file to a mount using the CLI, you can use the `mount:upload` command. 
+
+For example, to upload the files contained in the local `private` directory to the `private` mount,
+run the following command: 
+
+```bash
+$ platform mount:upload --mount private --source ./private
+```
+
+You get the following output:
+
+```bash
+Uploading files from ./private to the remote mount private
+
+Are you sure you want to continue? [Y/n]
+
+  sending incremental file list
+  example.sh
+
+  sent 2.35K bytes  received 20 bytes  1.58K bytes/sec
+  total size is 1.77M  speedup is 745.09
+```
+
+### Transfer a file from a mount
+
+To transfer a file from a mount using the CLI, you can use the `mount:download` command. 
+
+For example, to download a file from the `private` mount to your local `private` directory, 
+run the following command:
+
+```bash
+$ platform mount:download --mount private --target ./private
+```
+
+You get the following output:
+
+```bash
+Downloading files from the remote mount private to ./private
+
+Are you sure you want to continue? [Y/n]
+
+  receiving incremental file list
+  example.sh
+
+  sent 2.35K bytes  received 20 bytes  1.58K bytes/sec
+  total size is 1.77M  speedup is 745.09
+```
+
+## Transfer files using an SSH client
+
+Another way to transfer files to and from your built app is to use an SSH client such as [`scp`](file-transfer.md#scp) or [`rsync`](file-transfer.md#rsync).
+
+### scp
+
+As a command-line utility, `scp` lets you copy files to and from a remote environment.
+
+For example, to download a `diagram.png` file from the `web/uploads` directory 
+(relative to the [app root](../create-apps/app-reference.md#root-directory)),
+run the following command 
+(replacing {{< variable "PROJECT_ID" >}} and {{< variable "ENVIRONMENT_NAME" >}} with appropriate values):
+
+```bash
+scp "$(platform ssh --pipe -p {{< variable "PROJECT_ID" >}} -e {{< variable "ENVIRONMENT_NAME" >}}":web/uploads/diagram.png .
+```
+
+The `diagram.png` file is copied to the current local directory.
+
+To copy files from your local directory to the Platform.sh environment, 
+reverse the order of the parameters:
+
+```bash
+scp diagram.png "$(platform ssh --pipe -p {{< variable "PROJECT_ID" >}} -e {{< variable "ENVIRONMENT_NAME" >}})":web/uploads
+```
+
+For other options, see the [`scp` documentation](https://www.man7.org/linux/man-pages/man1/scp.1.html).
+
+### rsync
+
+You can use `rsync` to copy files to and from a remote environment.
+
+For example, to copy all the files in the `web/uploads` directory on the remote environment 
+to the local `uploads` directory,
+run the following command 
+(replacing {{< variable "PROJECT_ID" >}} and {{< variable "ENVIRONMENT_NAME" >}} with appropriate values):
+
+```bash
+rsync -az "$(platform ssh --pipe -p {{< variable "PROJECT_ID" >}} -e {{< variable "ENVIRONMENT_NAME" >}})":web/uploads/ ./uploads/
+```
+
+To copy files from your local directory to the Platform.sh environment, 
+reverse the order of the parameters:
+
+```bash
+rsync -az uploads/ "$(platform ssh --pipe -p {{< variable "PROJECT_ID" >}} -e {{< variable "ENVIRONMENT_NAME" >}})":web/uploads/
+```
+
+Note that `rsync` is very sensitive about trailing `/` characters.
+
+If you're using UTF-8 encoded files on macOS, 
+add the `--iconv=utf-8-mac,utf-8` flag to your `rsync` call.
+
+For more options, consult the [rsync documentation](https://man7.org/linux/man-pages/man1/rsync.1.html).

docs/src/development/headers.md

@@ -1,6 +1,6 @@
 ---
 title: "HTTP Headers"
-weight: 7
+weight: 8
 description: |
   Platform.sh adds a number of HTTP headers to both inbound and outbound messages. We don't modify or block existing headers on either request or response.
 sidebarTitle: "Headers"