docs: how to manage remote systems

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>
+```
+
+
 ## Identities
 
 Use named "identities" to allow additional users to access the API.
@@ -37,3 +49,15 @@ Use named "identities" to allow additional users to access the API.
 
 Manage identities <manage-identities>
 ```
+
+
+## API
+
+To integrate Pebble with your automated workflows, you can use the Pebble API.
+
+```{toctree}
+:titlesonly:
+:maxdepth: 1
+
+Use Pebble API <use-the-pebble-api>
+```

docs/how-to/manage-a-remote-system.md

@@ -0,0 +1,140 @@
+# How to use Pebble to manage a remote system
+
+Managing server clusters remotely takes time and effort. Servers need regular updates, configuration changes, file transfers, and commands run. Directly managing remote servers or using tools like Ansible, which require SSH, increases overhead and security risks. The [XZ Utils backdoor incident](https://en.wikipedia.org/wiki/XZ_Utils_backdoor) 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: "remote system" means clients can interact with the Pebble daemon via a unix socket.
+
+## 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.
+
+For example, if Pebble is running as 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 on the Pebble `exec` command, 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 easily. 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/pebble
+```
+
+Push our local website file to the remote system:
+
+```bash
+pebble push /tmp/index.html /var/www/pebble/index.html
+```
+
+Create a virtual host configuration _locally_:
+
+```
+cat <<EOF > /tmp/pebble
+server {
+       listen 81;
+       listen [::]:81;
+
+       server_name example.ubuntu.com;
+
+       root /var/www/pebble;
+       index index.html;
+
+       location / {
+               try_files \$uri \$uri/ =404;
+       }
+}
+EOF
+```
+
+Push the file to the remote system:
+
+```bash
+pebble push /tmp/pebble /etc/nginx/sites-enabled/pebble
+```
+
+Activate the newly added virtual host in the remote system by restarting Nginx:
+
+```bash
+pebble exec service nginx restart
+```
+
+Finally, we can test the final 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_rm_command`
+- {ref}`reference_pebble_push_command`
+- {ref}`reference_pebble_pull_command`
+
+## Use the API
+
+In the previous sections, we used Pebble commands to run commands and manage files. When automating these tasks, we can use the HTTP API that Pebble provides.
+
+For example, to push a file to the remote system, we can POST to the `/v1/files` endpoint:
+
+```bash
+curl --unix-socket /path/to/.pebble.socket -XPOST http://_/v1/files -H "Content-Type: multipart/form-data" -F request='{"action": "write", "files": [{"path": "/var/www/pebble/index.html", "make-dirs": true, "permissions": "644"}]}' -F 'files=@/tmp/index.html;type=application/octet-stream;filename=/var/www/pebble/index.html'
+```
+
+We can also use {ref}`api_go_client` and {ref}`api_python_client` for API access.
+
+## See more
+
+- [How to use the Pebble API to manage services](/how-to/use-the-pebble-api).
+- [API spec](/reference/api).