diff --git a/docs/src/development/access-site.md b/docs/src/development/access-site.md index 3f2009d9bd..2136c557bc 100644 --- a/docs/src/development/access-site.md +++ b/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 -``` - -{{< /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. -``` +
+ 
platform url --project {{< variable "PROJECT_ID" >}} --environment {{< variable "ENVIRONMENT_NAME" >}}
+
-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 `` 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 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. 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..1f91ea100d --- /dev/null +++ b/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 abcdefgh1234567-main-abcd123--app@ssh.eu.platform.sh: ++-------------------------+----------------------+ +| 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). \ 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" 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