From 7fce9de98a7b053cda7cfc04bebe94eded9d757a Mon Sep 17 00:00:00 2001 From: Anouck Date: Thu, 27 Oct 2022 15:43:17 +0200 Subject: [PATCH 1/6] :memo: Rework access site page and add file transfer page --- docs/src/development/access-site.md | 162 +++-------------------- docs/src/development/email.md | 2 +- docs/src/development/file-transfer.md | 178 ++++++++++++++++++++++++++ docs/src/development/headers.md | 2 +- 4 files changed, 196 insertions(+), 148 deletions(-) create mode 100644 docs/src/development/file-transfer.md diff --git a/docs/src/development/access-site.md b/docs/src/development/access-site.md index 3f2009d9bd..5f811ba28b 100644 --- a/docs/src/development/access-site.md +++ b/docs/src/development/access-site.md @@ -2,17 +2,11 @@ title: "Accessing 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**. + + You can copy and paste any of those 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 -``` - -{{< /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. -``` + ```bash + platform url --project + ``` -Uploading files to a mount is similar: +2. Follow the prompts to select the environment and URL you want to view 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 `` and `` with appropriate values): - -```bash -scp "$(platform ssh --pipe -p -e )":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 -e )":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 `` and `` with appropriate values): +{{< /codetabs >}} -```bash -rsync -az "$(platform ssh --pipe -p -e )":web/uploads/ ./uploads/ -``` +For more information about URLs in your project and how you can control access to your web applications, +see [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. diff --git a/docs/src/development/email.md b/docs/src/development/email.md index 9bf55ab65c..939e9cc66a 100644 --- a/docs/src/development/email.md +++ b/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. --- diff --git a/docs/src/development/file-transfer.md b/docs/src/development/file-transfer.md new file mode 100644 index 0000000000..0a9ed74573 --- /dev/null +++ b/docs/src/development/file-transfer.md @@ -0,0 +1,178 @@ +--- +title: "Transfer files to and from your app" +weight: 7 +sidebarTitle: File Transfer +--- + +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 app through mounts. +To do so, follow these steps. + +## Before you begin + +You need to [set up directories that remain writable after your app's build is complete](../create-apps/app-reference.md#mounts). +These are known as mounts. + +To upload and download files directly to and from a mount inside your built app, +you can then run a single command via the Platform.sh CLI +or an SSH client. + +## Transfer files using the CLI + +### 1. Optional: 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, in the Platform.sh CLI, run the following command: + +```bash +$ platform mounts +``` + +After selecting a project and an environment, you get an output similar to the following: + +```bash +Mounts in the app drupal (environment main): ++-------------------------+----------------------+ +| Path | Definition | ++-------------------------+----------------------+ +| web/sites/default/files | shared:files/files | +| private | shared:files/private | +| tmp | shared:files/tmp | ++-------------------------+----------------------+ +``` + +### 2. Transfer a file to a mount + +To transfer files to a mount using the CLI, you can use the `mount:upload` and `mount:download` commands. + +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 +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 + + 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. +``` + +Similarly, 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 +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. +``` + +## Transfer files using an SSH client + +Another way to transfer files to and from a mount is to use an SSH client. + +To do so, you need to connect to your app with SSH. +Follow these steps: + +1. Optional: If you've never done it before, [generate an SSH key and add it to your Platform account](../development/ssh/ssh-keys.md#add-ssh-keys). + +2. In the CLI, enter the following command +(replacing ``, `` and `` with appropriate values): + +```bash +platform ssh -p -e -A +``` + +When the connection is complete, you get an output similar to the following: + +```bash + ___ _ _ __ _ +| _ \ |__ _| |_ / _|___ _ _ _ __ __| |_ +| _/ / _` | _| _/ _ \ '_| ' \ _(_-< ' \ +|_| |_\__,_|\__|_| \___/_| |_|_|_(_)__/_||_| + + + Welcome to Platform.sh. + + This is environment main-bvxea6i + of project k7udf2g73jhbi. + +web@app.0:~$ + +``` + +You can now open another terminal +and start transferring files using an SSH client +such as `scp` or `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 `` and `` with appropriate values): + +```bash +scp "$(platform ssh --pipe -p -e )":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 -e )":web/uploads +``` + +See the [scp documentation](https://www.man7.org/linux/man-pages/man1/scp.1.html) for other options. + +### rsync + +`rync` is another tool you can use 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 `` and `` with appropriate values): + +```bash +rsync -az "$(platform ssh --pipe -p -e )":web/uploads/ ./uploads/ +``` + +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`. + + + \ No newline at end of file diff --git a/docs/src/development/headers.md b/docs/src/development/headers.md index 457d27d2af..6ccfc765e5 100644 --- a/docs/src/development/headers.md +++ b/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" From 16eac8dd61d3cb56ea273935cc8140724b68379d Mon Sep 17 00:00:00 2001 From: Anouck Date: Tue, 8 Nov 2022 10:59:45 +0100 Subject: [PATCH 2/6] :memo: Committed suggestions, added note and cleaned Exporting tutorial Co-authored-by: Aaron Collier --- docs/src/development/access-site.md | 10 +-- docs/src/development/file-transfer.md | 119 ++++++++++---------------- docs/src/tutorials/exporting.md | 48 ++--------- 3 files changed, 55 insertions(+), 122 deletions(-) diff --git a/docs/src/development/access-site.md b/docs/src/development/access-site.md index 5f811ba28b..53c6b09f54 100644 --- a/docs/src/development/access-site.md +++ b/docs/src/development/access-site.md @@ -1,5 +1,5 @@ --- -title: "Accessing your site" +title: "Access your site" weight: 6 description: | Find the URLs you can use to access your site via a web browser. @@ -20,7 +20,7 @@ highlight=false 2. From the **Environment** menu, select an environment. 3. Click **URLs**. - You can copy and paste any of those URLs into a web browser and access your site. +Copy and paste any of these URLs into a web browser and access your site. <---> @@ -33,14 +33,14 @@ highlight=false 1. Run the following command: ```bash - platform url --project + platform url --project {{< variable "PROJECT_ID" >}} --environment {{< variable "ENVIRONMENT_NAME" >}} ``` -2. Follow the prompts to select the environment and URL you want to view in a browser. +2. Select the URL to open in a browser. {{< /codetabs >}} For more information about URLs in your project and how you can control access to your web applications, -see [Define routes](../define-routes/). +see how to [define routes](../define-routes/). diff --git a/docs/src/development/file-transfer.md b/docs/src/development/file-transfer.md index 0a9ed74573..025a6364fd 100644 --- a/docs/src/development/file-transfer.md +++ b/docs/src/development/file-transfer.md @@ -1,37 +1,39 @@ --- title: "Transfer files to and from your app" weight: 7 -sidebarTitle: File Transfer +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. +After your app is built, its file system is read-only. -However, you can transfer files to and from your app through mounts. -To do so, follow these steps. +The only way you can transfer files to your built app without using Git is through [mounts](../create-apps/app-reference.md#mounts). +Mounts let you set up directories that remain writable after the build is complete. +You can then upload files directly to mounts inside your app. + +To download files from your built app, +you can also use mounts or [an alternative data export method](../tutorials/exporting.md). ## Before you begin -You need to [set up directories that remain writable after your app's build is complete](../create-apps/app-reference.md#mounts). -These are known as mounts. +Make sure you [set up mounts](../create-apps/app-reference.md#mounts). To upload and download files directly to and from a mount inside your built app, -you can then run a single command via the Platform.sh CLI +you can then run a single command via the [Platform.sh CLI](../administration/cli/_index.md) or an SSH client. ## Transfer files using the CLI -### 1. Optional: View the mounts inside your app +### 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, in the Platform.sh CLI, run the following command: +To do so, run the following command: ```bash -$ platform mounts +$ platform mounts --project {{< variable "PROJECT_ID" >}} --environment {{< variable "ENVIRONMENT_NAME" >}} ``` -After selecting a project and an environment, you get an output similar to the following: +The output is similar to the following: ```bash Mounts in the app drupal (environment main): @@ -44,34 +46,11 @@ Mounts in the app drupal (environment main): +-------------------------+----------------------+ ``` -### 2. Transfer a file to a mount - -To transfer files to a mount using the CLI, you can use the `mount:upload` and `mount:download` commands. - -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 -``` +### Transfer a file to a mount -You get the following output: +To transfer a file to a mount using the CLI, you can use the `mount:upload` command. -```bash -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 - - 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. -``` - -Similarly, to upload the files contained in the local `private` directory to the `private` mount, +For example, to upload the files contained in the local `private` directory to the `private` mount, run the following command: ```bash @@ -94,43 +73,36 @@ Uploading files from /Users/alice/Projects/foo/private to the remote mount /app/ The upload completed successfully. ``` -## Transfer files using an SSH client - -Another way to transfer files to and from a mount is to use an SSH client. +### Transfer a file from a mount -To do so, you need to connect to your app with SSH. -Follow these steps: +To transfer a file from a mount using the CLI, you can use the `mount:download` command. -1. Optional: If you've never done it before, [generate an SSH key and add it to your Platform account](../development/ssh/ssh-keys.md#add-ssh-keys). - -2. In the CLI, enter the following command -(replacing ``, `` and `` with appropriate values): +For example, to download a file from the `private` mount to your local `private` directory, +run the following command: ```bash -platform ssh -p -e -A +$ platform mount:download --mount private --target ./private ``` -When the connection is complete, you get an output similar to the following: +You get the following output: ```bash - ___ _ _ __ _ -| _ \ |__ _| |_ / _|___ _ _ _ __ __| |_ -| _/ / _` | _| _/ _ \ '_| ' \ _(_-< ' \ -|_| |_\__,_|\__|_| \___/_| |_|_|_(_)__/_||_| - - - Welcome to Platform.sh. - - This is environment main-bvxea6i - of project k7udf2g73jhbi. +This will add, replace, and delete files in the local directory 'private'. -web@app.0:~$ +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 + 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. ``` -You can now open another terminal -and start transferring files using an SSH client -such as `scp` or `rsync`. +## Transfer files using an SSH client + +Another way to transfer files to and from a mount is to use an SSH client such as [`scp`](file-transfer.md#scp) or [`rsync`](file-transfer.md#rsync). ### scp @@ -139,10 +111,10 @@ As a command-line utility, `scp` lets you copy files to and from a remote enviro 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 `` and `` with appropriate values): +(replacing {{< variable "PROJECT_ID" >}} and {{< variable "ENVIRONMENT_NAME" >}} with appropriate values): ```bash -scp "$(platform ssh --pipe -p -e )":web/uploads/diagram.png . +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. @@ -154,25 +126,24 @@ reverse the order of the parameters: scp diagram.png "$(platform ssh --pipe -p -e )":web/uploads ``` -See the [scp documentation](https://www.man7.org/linux/man-pages/man1/scp.1.html) for other options. +For other options, see the [`scp` documentation](https://www.man7.org/linux/man-pages/man1/scp.1.html). ### rsync -`rync` is another tool you can use to copy files to and from a remote environment. +You can use `rync` 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 `` and `` with appropriate values): +(replacing {{< variable "PROJECT_ID" >}} and {{< variable "ENVIRONMENT_NAME" >}} with appropriate values): ```bash -rsync -az "$(platform ssh --pipe -p -e )":web/uploads/ ./uploads/ +rsync -az "$(platform ssh --pipe -p {{< variable "PROJECT_ID" >}} -e {{< variable "ENVIRONMENT_NAME" >}})":web/uploads/ ./uploads/ ``` -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`. +Note that `rsync` is very sensitive about trailing `/` characters. +Also, if you're a MacOS user handling UTF-8 encoded files, +add the `--iconv=utf-8-mac,utf-8` flag to your `rsync`call. - \ No newline at end of file +Consult the [rsync documentation](https://man7.org/linux/man-pages/man1/rsync.1.html) for more details. \ No newline at end of file diff --git a/docs/src/tutorials/exporting.md b/docs/src/tutorials/exporting.md index d7e50a21d4..64de8416d6 100644 --- a/docs/src/tutorials/exporting.md +++ b/docs/src/tutorials/exporting.md @@ -14,50 +14,12 @@ you can download your entire code history by running `git clone` or `platform ge ## Downloading files -Your application runs on a read-only file system, so it can't be edited. -That means there's nothing to download from most of it that isn't already in your Git repository. +To download files from your built app, +you can [set up mounts](../create-apps/app-reference.md#mounts) +and run commands using the Platform.sh CLI. +You can also use an SSH client such as `rsync` or `scp`. -The only files to download are from any writable file mounts you may have defined in your `.platform.app.yaml` file. -The easiest way to download those is using the `rsync` tool. -For instance, suppose you have a mounts section that defines one web-accessible directory and one non-web-accessible directory: - -```yaml -mounts: - 'web/uploads': - source: local - source_path: uploads - 'private': - source: local - source_path: private -``` -### Using the CLI - -The CLI provides a useful `mount` command for accessing mount data. - -```bash -platform mount:list -``` - -Download a mount by running the following: - -```bash -platform mount:download -``` - -### Using rsync -To use `rsync` to download each directory, we can use the following commands. The `platform ssh --pipe` command will return the SSH URL for the current environment as an inline string that `rsync` can recognize. To use a non-default environment, use the `-e` flag with an environment name after `--pipe`. Note that the trailing slash on the remote path means `rsync` will copy just the files inside the specified directory, not the directory itself. - -```bash -rsync -az `platform ssh --pipe`:/app/private/ ./private/ -rsync -az `platform ssh --pipe`:/app/web/uploads ./uploads/ -``` - - -{{< note >}} -If you're running `rsync` on MacOS, you should add `--iconv=utf-8,utf-8-mac` to your `rsync` call. -{{< /note >}} - -See the [`rsync` documentation](https://download.samba.org/pub/rsync/rsync.html) for more details on how to adjust the download process. +For more information, see how to [transfer files to and from a built app](../development/file-transfer.md). ## Download data from services From 9bcd4af56b57c5f1ca2f4f5b4f287128731ef75c Mon Sep 17 00:00:00 2001 From: AnouckColson <113913013+AnouckColson@users.noreply.github.com> Date: Wed, 9 Nov 2022 09:41:19 +0100 Subject: [PATCH 3/6] Apply suggestions from code review Co-authored-by: Aaron Collier --- docs/src/development/access-site.md | 6 ++-- docs/src/development/file-transfer.md | 45 +++++++++++++-------------- 2 files changed, 25 insertions(+), 26 deletions(-) diff --git a/docs/src/development/access-site.md b/docs/src/development/access-site.md index 53c6b09f54..2136c557bc 100644 --- a/docs/src/development/access-site.md +++ b/docs/src/development/access-site.md @@ -32,9 +32,9 @@ highlight=false 1. Run the following command: - ```bash - platform url --project {{< variable "PROJECT_ID" >}} --environment {{< variable "ENVIRONMENT_NAME" >}} - ``` +
+ 
platform url --project {{< variable "PROJECT_ID" >}} --environment {{< variable "ENVIRONMENT_NAME" >}}
+
2. Select the URL to open in a browser. diff --git a/docs/src/development/file-transfer.md b/docs/src/development/file-transfer.md index 025a6364fd..65679f45cc 100644 --- a/docs/src/development/file-transfer.md +++ b/docs/src/development/file-transfer.md @@ -36,13 +36,16 @@ $ platform mounts --project {{< variable "PROJECT_ID" >}} --environment {{< vari The output is similar to the following: ```bash -Mounts in the app drupal (environment main): +Mounts on abcdefgh1234567-main-abcd123--app@ssh.eu.platform.sh: +-------------------------+----------------------+ -| Path | Definition | +| Mount path | Definition | +-------------------------+----------------------+ -| web/sites/default/files | shared:files/files | -| private | shared:files/private | -| tmp | shared:files/tmp | +| web/sites/default/files | source: local | +| | source_path: files | +| private | source: local | +| | source_path: private | +| tmp | source: local | +| | source_path: temp | +-------------------------+----------------------+ ``` @@ -60,17 +63,15 @@ $ platform mount:upload --mount private --source ./private You get the following output: ```bash -This will add, replace, and delete files in the remote mount 'private'. +Uploading files from ./private to 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 + + 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 - time: 0.72s -The upload completed successfully. ``` ### Transfer a file from a mount @@ -87,17 +88,15 @@ $ platform mount:download --mount private --target ./private You get the following output: ```bash -This will add, replace, and delete files in the local directory 'private'. +Downloading files from the remote mount private to ./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 - - 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. + + 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 @@ -123,7 +122,7 @@ 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 -e )":web/uploads +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). @@ -143,7 +142,7 @@ rsync -az "$(platform ssh --pipe -p {{< variable "PROJECT_ID" >}} -e {{< variabl Note that `rsync` is very sensitive about trailing `/` characters. -Also, if you're a MacOS user handling UTF-8 encoded files, +If you're using UTF-8 encoded files on macOS, add the `--iconv=utf-8-mac,utf-8` flag to your `rsync`call. -Consult the [rsync documentation](https://man7.org/linux/man-pages/man1/rsync.1.html) for more details. \ No newline at end of file +For more options, consult the [rsync documentation](https://man7.org/linux/man-pages/man1/rsync.1.html). \ No newline at end of file From b24b72172c5c8894bcf7767894f3b741a0cfc7c7 Mon Sep 17 00:00:00 2001 From: Anouck Date: Wed, 9 Nov 2022 10:52:55 +0100 Subject: [PATCH 4/6] :memo: Rework introduction and improve accuracy --- docs/src/development/file-transfer.md | 31 +++++++++++++++------------ 1 file changed, 17 insertions(+), 14 deletions(-) diff --git a/docs/src/development/file-transfer.md b/docs/src/development/file-transfer.md index 65679f45cc..5f26ff45a7 100644 --- a/docs/src/development/file-transfer.md +++ b/docs/src/development/file-transfer.md @@ -5,21 +5,17 @@ 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 files and code is through Git. -The only way you can transfer files to your built app without using Git is through [mounts](../create-apps/app-reference.md#mounts). -Mounts let you set up directories that remain writable after the build is complete. -You can then upload files directly to mounts inside your app. - -To download files from your built app, -you can also use mounts or [an alternative data export method](../tutorials/exporting.md). - -## Before you begin +However, you can transfer files to and from your built app without using Git. -Make sure you [set up mounts](../create-apps/app-reference.md#mounts). +To do so, you need to configure [mounts](../create-apps/app-reference.md#mounts). +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). -To upload and download files directly to and from a mount inside your built app, -you can then run a single command via the [Platform.sh CLI](../administration/cli/_index.md) -or an SSH client. +Alternatively, you can transfer files to and from your built app +using an SSH client such `scp` and `rsync`. ## Transfer files using the CLI @@ -101,7 +97,7 @@ Are you sure you want to continue? [Y/n] ## Transfer files using an SSH client -Another way to transfer files to and from a mount is to use an SSH client such as [`scp`](file-transfer.md#scp) or [`rsync`](file-transfer.md#rsync). +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 @@ -129,7 +125,7 @@ For other options, see the [`scp` documentation](https://www.man7.org/linux/man- ### rsync -You can use `rync` to copy files to and from a remote environment. +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, @@ -140,6 +136,13 @@ run the following command 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, From c076ba48d666d62c8d7b62cb3c2c2ae091aba77d Mon Sep 17 00:00:00 2001 From: AnouckColson <113913013+AnouckColson@users.noreply.github.com> Date: Wed, 9 Nov 2022 15:52:00 +0100 Subject: [PATCH 5/6] Apply suggestions from code review Co-authored-by: Aaron Collier --- docs/src/development/file-transfer.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/src/development/file-transfer.md b/docs/src/development/file-transfer.md index 5f26ff45a7..012f438b2e 100644 --- a/docs/src/development/file-transfer.md +++ b/docs/src/development/file-transfer.md @@ -5,7 +5,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 files and code is through Git. +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. @@ -146,6 +146,6 @@ rsync -az uploads/ "$(platform ssh --pipe -p {{< variable "PROJECT_ID" >}} -e {{ 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. +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). \ No newline at end of file From 7a023f312188ee18395bdae579ce066c303e8ca8 Mon Sep 17 00:00:00 2001 From: Anouck Date: Wed, 9 Nov 2022 16:33:25 +0100 Subject: [PATCH 6/6] :memo: Rework introduction --- docs/src/development/file-transfer.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/src/development/file-transfer.md b/docs/src/development/file-transfer.md index 012f438b2e..1f91ea100d 100644 --- a/docs/src/development/file-transfer.md +++ b/docs/src/development/file-transfer.md @@ -8,14 +8,14 @@ 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. -To do so, you need to configure [mounts](../create-apps/app-reference.md#mounts). -Mounts let you set up directories that remain writable after the build is complete. +[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 `scp` and `rsync`. +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