canonical · IronCore864 · Jan 23, 2025 · Dec 31, 2024 · Jan 4, 2025 · Jan 6, 2025
diff --git a/docs/how-to/index.md b/docs/how-to/index.md
@@ -27,6 +27,18 @@ Manage service dependencies <service-dependencies>
 ```
 
 
+## Manage a remote system
+
+Pebble provides exec and file management functions to coordinate with remote systems.
+
+```{toctree}
+:titlesonly:
+:maxdepth: 1
+
+Manage a remote system <manage-a-remote-system>
+```
+
+
 ## Logging
 
 To better understand the operation of the services, you may need to work with logs.

diff --git a/docs/how-to/manage-a-remote-system.md b/docs/how-to/manage-a-remote-system.md
@@ -0,0 +1,129 @@
+# How to use Pebble to manage a remote system
+
+Managing server clusters remotely takes time and effort. Servers need regular updates and configuration changes, which typically involves transferring files and running commands. Directly managing remote servers or using tools that require SSH access (such as Ansible) increases overhead and security risks. The [XZ Utils backdoor incident](https://en.wikipedia.org/wiki/XZ_Utils_backdoor) in 2024 highlighted vulnerabilities associated with SSH access.
+
+Pebble offers commands and an HTTP API over Unix socket for remote system management, avoiding the need for extra open ports. 
+
+> Note: By "remote system", we mean that the Pebble daemon is running in a separate system and there's a Unix socket for clients to interact with the daemon.
+
+## Run commands in a remote system
+
+One common task in system administration is updating and installing packages. With Pebble, we can use the `pebble exec` command to achieve this.
+
+> Note: Set the environment variable `PEBBLE_SOCKET` to override the Unix socket used for the API (defaults to `$PEBBLE/.pebble.socket`, or to `/var/lib/pebble/default/.pebble.socket` if `PEBBLE` is not set).
+
+For example, if Pebble is running as a user with root privileges, we can use this command to update and install packages in a remote system:
+
+```{terminal}
+:input: pebble exec apt update
+Hit:1 http://ports.ubuntu.com/ubuntu-ports noble InRelease
+Get:2 http://ports.ubuntu.com/ubuntu-ports noble-updates InRelease [126 kB]
+Get:3 http://ports.ubuntu.com/ubuntu-ports noble-backports InRelease [126 kB]
+...
+Fetched 3121 kB in 38s (81.5 kB/s)
+Reading package lists... Done
+Building dependency tree... Done
+Reading state information... Done
+41 packages can be upgraded. Run 'apt list --upgradable' to see them.
+```
+
+To install a package, run:
+
+```bash
+pebble exec apt install cowsay
+```
+
+To confirm the package is successfully installed in the remote system, run:
+
+```{terminal}
+:input: pebble exec cowsay moo
+ _____
+< moo >
+ -----
+        \   ^__^
+         \  (oo)\_______
+            (__)\       )\/\
+                ||----w |
+                ||     ||
+```
+
+For more information, see {ref}`reference_pebble_exec_command`.
+
+## Manage files in a remote system
+
+Another common task in a remote system is configuration management. For example, updating configuration files, pushing files to servers, pulling files generated by running services, and so on.
+
+With Pebble, this can be done using its file commands. For example, if we want to install Nginx, create our own website, and serve it on a newly created virtual host, we can first install Nginx:
+
+```bash
+pebble exec apt install nginx
+```
+
+Then create our website _locally_:
+
+```bash
+echo "Hello, Pebble!" > /tmp/index.html
+```
+
+Create a directory in the remote system:
+
+```bash
+pebble mkdir -p /var/www/demo
+```
+
+Push our local website file to the remote system:
+
+```bash
+pebble push /tmp/index.html /var/www/demo/index.html
+```
+
+Create a virtual host configuration _locally_:
+
+```
+cat <<EOF > /tmp/demo
+server {
+       listen 81;
+       listen [::]:81;
+
+       server_name example.ubuntu.com;
+
+       root /var/www/demo;
+       index index.html;
+
+       location / {
+               try_files \$uri \$uri/ =404;
+       }
+}
+EOF
+```
+
+Push the file to the remote system:
+
+```bash
+pebble push /tmp/demo /etc/nginx/sites-enabled/demo
+```
+
+Activate the newly added virtual host in the remote system by restarting Nginx:
+
+```bash
+pebble exec service nginx restart
+```
+
+Finally, we can test the result:
+
+```{terminal}
+:input: curl localhost:81
+Hello, Pebble!
+```
+
+For more information about related Pebble commands, see:
+
+- {ref}`reference_pebble_ls_command`
+- {ref}`reference_pebble_mkdir_command`
+- {ref}`reference_pebble_pull_command`
+- {ref}`reference_pebble_push_command`
+- {ref}`reference_pebble_rm_command`
+
+## See more
+
+You can also use the Pebble API to run command and manage files. This is normally done using the Go or Python client libraries. For more information, see [How to use the Pebble API](/how-to/use-the-pebble-api).
diff --git a/docs/index.md b/docs/index.md
@@ -29,7 +29,6 @@ Pebble is useful for developers who are building [Juju charms on Kubernetes](htt
 **Technical information**
 - [Layer specification](reference/layer-specification)
 - [CLI commands](reference/cli-commands)
-- [Pebble in containers](reference/pebble-in-containers)
 ```
 
 ```{grid-item-card} [Explanation](explanation/index)

diff --git a/docs/reference/api.md b/docs/reference/api.md
@@ -51,6 +51,7 @@ We try to never change the underlying HTTP API in a backwards-incompatible way.
 
 For more information, see the [Go client documentation](https://pkg.go.dev/github.com/canonical/pebble/client).
 
+(api_python_client)=
 ### Python client
 
 The Ops library for writing and testing Juju charms includes a [Python client for Pebble API](https://ops.readthedocs.io/en/latest/reference/pebble.html). You can use the Python client to access the API endpoints over the Unix socket. For example:

diff --git a/docs/reference/cli-commands.md b/docs/reference/cli-commands.md
@@ -191,7 +191,7 @@ error: cannot perform the following tasks:
 - exec command "sleep" (timed out after 1s: context deadline exceeded)
 ```
 
-Read more: [Use Pebble in containers](pebble-in-containers.md).
+Read more: [How to use Pebble to manage remote systems](/how-to/manage-a-remote-system.md).
 
 
 (reference_pebble_health_command)=
@@ -410,7 +410,7 @@ may be specified for the last path element.
 ```
 <!-- END AUTOMATED OUTPUT FOR ls -->
 
-Read more: [Use Pebble in containers](pebble-in-containers.md).
+Read more: [How to use Pebble to manage remote systems](/how-to/manage-a-remote-system.md).
 
 
 (reference_pebble_mkdir_command)=
@@ -437,7 +437,7 @@ The mkdir command creates the specified directory.
 ```
 <!-- END AUTOMATED OUTPUT FOR mkdir -->
 
-Read more: [Use Pebble in containers](pebble-in-containers.md).
+Read more: [How to use Pebble to manage remote systems](/how-to/manage-a-remote-system.md).
 
 
 (reference_pebble_notice_command)=
@@ -640,7 +640,7 @@ The pull command retrieves a file from the remote system.
 ```
 <!-- END AUTOMATED OUTPUT FOR pull -->
 
-Read more: [Use Pebble in containers](pebble-in-containers.md).
+Read more: [How to use Pebble to manage remote systems](/how-to/manage-a-remote-system.md).
 
 
 (reference_pebble_push_command)=
@@ -666,7 +666,7 @@ The push command transfers a file to the remote system.
 ```
 <!-- END AUTOMATED OUTPUT FOR push -->
 
-Read more: [Use Pebble in containers](pebble-in-containers.md).
+Read more: [How to use Pebble to manage remote systems](/how-to/manage-a-remote-system.md).
 
 
 (reference_pebble_remove-identities_command)=
@@ -810,7 +810,7 @@ The rm command removes a file or directory.
 ```
 <!-- END AUTOMATED OUTPUT FOR rm -->
 
-Read more: [Use Pebble in containers](pebble-in-containers.md).
+Read more: [How to use Pebble to manage remote systems](/how-to/manage-a-remote-system.md).
 
 
 (reference_pebble_run_command)=

diff --git a/docs/reference/index.md b/docs/reference/index.md
@@ -20,7 +20,6 @@ Layers <layers>
 Layer specification <layer-specification>
 Log forwarding <log-forwarding>
 Notices <notices>
-Pebble in containers <pebble-in-containers>
 Service auto-restart <service-auto-restart>
 ```
 
@@ -43,13 +42,6 @@ The `pebble` command has several subcommands.
 * [CLI commands](cli-commands)
 
 
-## Pebble in containers
-
-When the Pebble daemon is running inside a remote system (for example, a separate container), you can manage the remote system using subcommands on the Pebble client.
-
-* [Pebble in containers](pebble-in-containers)
-
-
 ## Service failures
 
 Pebble provides two ways to automatically restart services when they fail. Auto-restart is based on exit codes from services. Health checks are a more sophisticated way to test and report the availability of services.

diff --git a/docs/reference/pebble-in-containers.md b/docs/reference/pebble-in-containers.md