docs: simplify common CapRover workflows (#254)

* docs: simplify common CapRover workflows

* docs: clarify update, image upgrade, and rollback steps

Author: githubsaturn

content/README.md

@@ -113,6 +113,8 @@ Optimize documentation for fast scanning:
 - Put prerequisites in brief bullet lists. Name the requirement, then the value.
 - Use numbered steps for procedures and bullets for options, requirements, and caveats.
 - Put commands, configuration examples, and tables near the action they support.
+- Lead with the shortest supported workflow. Keep optional checks and advanced recovery in their own sections.
+- Put warnings next to the action they apply to and state the specific risk.
 - Explain unusual ports, flags, and risks inline. Skip explanations of self-evident steps.
 - Prefer imperative sentences: **Set the root domain** instead of **You can set the root domain**.
 - Keep bullets focused on one idea. Split dense bullets into steps, tables, or smaller bullets.

content/en/docs-next/data-persistence/deploy-databases.md

@@ -4,14 +4,13 @@ title: Deploy Databases
 slug: /data-persistence/deploy-databases
 ---
 
-- A database on CapRover is an app that needs storage, credentials, and a network path for its clients.
 - The [One-Click Apps](../one-click-apps/index.md) catalog can create a supported database service, or you can deploy a database image yourself.
 
 1. Choose the database and image version. Create its app with **Has Persistent Data** enabled and leave **Do not expose as web app** selected; databases generally do not serve HTTP through NGINX.
 2. Configure the database's required username, password, and database name through its app settings or One-Click installer. Use unique credentials and keep them out of source control.
 3. Mount a named volume or bind path at the database image's actual data directory. Place the app on the node holding that storage.
 4. Deploy and read the service logs until the database reports it is ready. Restart or redeploy once to confirm its data remains present.
-5. Connect another app by the database service name and internal container port. Publish a host port only if an external client needs it; follow the [external connection guide](deploy-databases.md) for its firewall and security steps.
+5. Connect another app by the database service name and internal container port. Publish a host port only if an external client needs it; follow the [external connection guide](#connect-to-databases-externally) for its firewall and security steps.
 6. Schedule database-aware backups and test a restore. The CapRover configuration backup does not contain the database records.
 
 Check the chosen database image's storage path and initialization variables; they differ between PostgreSQL, MySQL, Redis, and other services.
@@ -40,10 +39,7 @@ Check the chosen database image's storage path and initialization variables; the
 
 ### Prepare the database
 
-- Deploy the database as a persistent, non-web app.
-- Configure its data volume or bind mount, credentials, and database name.
-- Verify it is ready in its service logs and that a CapRover app can reach it internally by app name and container port.
-- Back up the database data separately from the CapRover configuration.
+Deploy the database as described above and check its logs for readiness before opening access.
 
 ### Publish a restricted port
 

content/en/docs-next/deployments/builds-logs.md

@@ -19,9 +19,7 @@ slug: /deployments/builds-logs
 
 ## Versions and Rollback
 
-- CapRover records image versions for an app.
-- From the app's deployment history, choose a previously deployed version to roll back its image.
-- Check the result and app health before resuming traffic.
+In the app’s **Deployment** tab, open **Version History**, click **Revert to this version** on the row for the image you want, and confirm.
 
 - Rollback does **not** restore earlier environment variables, domains, volume contents, or database schema.
 - If the newer version changed persistent data, confirm the older image remains compatible before rolling back.

content/en/docs-next/deployments/index.md

@@ -12,15 +12,7 @@ slug: /deployments
 - To deploy an archive, package the project with its `captain-definition` file at the expected path and upload the tar file.
 - The dashboard also accepts a Captain Definition pasted into its text input when no source files are needed.
 
-For example, paste this definition to deploy an existing public image:
-
-```json
-{"schemaVersion":2,"imageName":"nginx:stable-alpine"}
-```
-
-- Start the deployment, watch the build or pull status, then verify the app's container HTTP port and its default domain.
-- For a private image, configure registry credentials first.
-- See [Deploy a Docker Image](index.md).
+[Deploy an existing Docker image](#deploy-a-docker-image)
 
 <span id="source-deployments-docker-image"></span>
 

content/en/docs-next/get-started.md

@@ -22,15 +22,12 @@ On the server:
 ```bash
 sudo apt update && sudo apt install -y curl
 curl -fsSL https://get.caprover.com -o caprover-install.sh
-sudo bash caprover-install.sh --check
 sudo bash caprover-install.sh
 ```
 
-- [Installer source and options](https://github.com/caprover/caprover/tree/master/scripts/user/installer). Review the downloaded script before running it as root.
-- `--check`: read-only checks for OS, RAM, disk, Docker, Swarm, ports, and firewall conflicts. Resolve blocking issues before installing.
-- The installer installs Docker Engine when absent and preserves existing Docker workloads.
-- On an active UFW firewall, it allows TCP 80/443/3000. It leaves inactive UFW and hosting-provider firewalls unchanged.
-- After installation, it checks external port reachability and reports warnings. DNS, dashboard configuration, and HTTPS remain manual.
+[Installer source and options](https://github.com/caprover/caprover/tree/master/scripts/user/installer)
+
+For a read-only check, run `sudo bash caprover-install.sh --check`.
 
 **Other methods:** [Manual Setup](installation/manual.md) (Docker and CapRover commands), [DigitalOcean Marketplace](installation/index.md), or [Advanced Installation](installation/advanced/index.md) for private networks, existing Swarms, and custom ports.
 

content/en/docs-next/one-click-apps/index.md

@@ -39,10 +39,9 @@ One-Click templates create ordinary CapRover apps. Each template may provision m
 
 ## Upgrades
 
-- Read the upstream application's migration instructions and back up its data before upgrading.
-- A template can use a custom image or initialization scripts. Replacing it with a plain upstream image may lose essential configuration.
-- Image changes do not perform every database or application-schema migration.
-- Preserve and verify existing volumes when recreating or migrating stateful apps.
+For apps that support an image-only upgrade, follow the upstream instructions for any required backups or migrations. If the template uses a custom image or initialization scripts, check how the upgrade will preserve that configuration.
+
+In the app’s **Deployment** tab, open **Method 6: Deploy via ImageName**, enter the new image and tag, and deploy.
 
 <span id="source-one-click-apps-custom-repositories"></span>
 

content/en/docs-next/server/index.md

@@ -8,7 +8,7 @@ slug: /server
 
 ## Server Settings
 
-Use the dashboard's **Settings** area to manage the root domain, account password, updates, and CapRover backups. Back up the server before changing its domain or upgrading.
+Open **Settings** to manage the root domain and account password. Open **Maintenance** to [update CapRover](upgrade.md) or [download a configuration backup](backup/index.md).
 
 ### Root domain
 

content/en/docs-next/server/upgrade.md

@@ -4,19 +4,25 @@ title: Upgrade CapRover
 slug: /server/upgrade
 ---
 
-Before upgrading, [download a CapRover backup](backup/index.md) and separately back up application data and volumes. Check the release notes and confirm your Docker host has enough free disk space.
+In the dashboard, open **Maintenance → CapRover Updates** and click **Install Update** when a stable update is available. On older dashboards, look under **Settings**.
 
-- In the dashboard, open **Settings** and inspect the current version, available version, and change log.
-- Use the dashboard update action when it reports that an update is available.
-- CapRover pulls the selected image and updates the `captain-captain` Docker service.
-- Allow the service time to restart, then verify the dashboard, deployed apps, registry, and HTTPS.
+Run these commands on the Swarm manager.
 
-- If the update fails, check `docker service ps captain-captain --no-trunc` and `docker service logs captain-captain --tail 100` on the manager node.
-- Preserve a backup and the previous image tag before attempting a rollback; see [Diagnostics](../troubleshooting/diagnostics.md).
+<span id="testing-an-edge-image"></span>
 
-## Testing an edge image
+## Switch to edge
 
-- For an advanced, temporary test of a fix available only in the edge image, record the exact current image from `docker service inspect captain-captain`, back up CapRover and app data, and then update the service image to a **specific tested edge tag or digest** using `docker service update captain-captain --image IMAGE`.
-- This bypasses the dashboard's normal version flow.
-- Edge images may not support downgrading to the currently released version; wait for a compatible release or restore a tested backup before switching back.
-- Verify dashboard, apps, and service logs after any manual update.
+```bash
+docker pull caprover/caprover-edge:latest
+docker service update captain-captain --image caprover/caprover-edge:latest
+```
+
+## Switch back to stable
+
+```bash
+docker service update captain-captain --image caprover/caprover:latest
+```
+
+Switching back may fail if the edge release introduced changes incompatible with the stable release.
+
+If the update fails, see [Diagnostics](../troubleshooting/diagnostics.md).

content/es-ES/docs-next/data-persistence/deploy-databases.md

@@ -4,14 +4,13 @@ title: Desplegar bases de datos
 slug: /data-persistence/deploy-databases
 ---
 
-- En CapRover, una base de datos es una aplicación que necesita almacenamiento persistente, credenciales y conectividad de red para sus clientes.
 - Puedes instalar una base de datos mediante el catálogo de [One-Click Apps](../one-click-apps/index.md) o desplegar directamente una imagen compatible.
 
 1. Elige el motor y la versión de la imagen. Crea la aplicación con **Has Persistent Data** activado y **Do not expose as web app** seleccionado; normalmente las bases de datos no sirven HTTP a través de NGINX.
 2. Configura el usuario, la contraseña y el nombre de la base de datos mediante los ajustes de la aplicación o el instalador One-Click. Utiliza credenciales únicas y mantenlas fuera del repositorio.
 3. Monta un volumen con nombre o un bind mount en el directorio de datos real de la imagen. Asigna la aplicación al nodo que contiene ese almacenamiento.
 4. Despliega la base de datos y consulta los logs hasta que esté lista para aceptar conexiones. Reinicia o vuelve a desplegar una vez para comprobar que los datos persisten.
-5. Desde otra aplicación, conecta usando el nombre del servicio y el puerto interno del contenedor. Publica un puerto del host solo si necesitas clientes externos; sigue los pasos de firewall y seguridad de la [guía de conexión externa](deploy-databases.md).
+5. Desde otra aplicación, conecta usando el nombre del servicio y el puerto interno del contenedor. Publica un puerto del host solo si necesitas clientes externos; sigue los pasos de firewall y seguridad de la [guía de conexión externa](#conectar-a-bases-de-datos-desde-fuera-de-caprover).
 6. Programa backups específicos para ese motor de base de datos y prueba una restauración. El backup de configuración de CapRover no incluye los registros de la base de datos.
 
 Consulta la documentación de la imagen elegida para verificar rutas de datos y variables de inicialización; pueden variar entre PostgreSQL, MySQL, Redis y otros servicios.
@@ -40,10 +39,7 @@ Consulta la documentación de la imagen elegida para verificar rutas de datos y
 
 ### Preparar la base de datos
 
-- Despliega la base de datos como una aplicación persistente sin exposición web.
-- Configura el volumen o bind mount, las credenciales y el nombre de la base de datos.
-- Comprueba en los logs que está lista y verifica que otra aplicación de CapRover pueda conectarse mediante el nombre del servicio y el puerto interno.
-- Haz una copia de seguridad de los datos de la base de datos por separado de la configuración de CapRover.
+Despliega la base de datos como se describe arriba y comprueba en los logs que esté lista antes de habilitar el acceso.
 
 ### Publicar un puerto restringido
 

content/es-ES/docs-next/deployments/builds-logs.md

@@ -19,9 +19,7 @@ slug: /deployments/builds-logs
 
 ## Versiones y rollback
 
-- CapRover guarda el historial de versiones de imágenes de cada aplicación.
-- Desde el historial de despliegues, elige una versión anterior para hacer rollback de la imagen.
-- Comprueba el resultado y la salud de la aplicación antes de reanudar el tráfico.
+En **Deployment**, abre **Version History**, haz clic en **Revert to this version** en la fila de la imagen que quieres restaurar y confirma.
 
 - Un rollback **no** restaura variables de entorno anteriores, dominios, datos de volúmenes ni el esquema de la base de datos.
 - Si la nueva versión modificó datos persistentes, comprueba la compatibilidad de la imagen anterior antes de hacer rollback.