v4.x documentation updates

.gitignore

@@ -34,3 +34,5 @@ pnpm-debug.log*
 # typescript
 *.tsbuildinfo
 next-env.d.ts
+
+.idea/*

content/docs/4.x/admin/export-import.md

@@ -0,0 +1,38 @@
+# Export & Import
+
+## Introduction
+
+Vito can export everything it has stored into a single backup file, and import it back into another
+instance. This is useful for migrating to a new Vito instance, or for keeping a backup of your
+current one.
+
+## Export
+
+From **Admin > Export & Import**, click **Export** to download a backup. The file is a zip named
+`vito-backup-YYYY-MM-DD.zip` and contains:
+
+- The Vito database (`database.sqlite`), which holds your servers, sites, projects, users, logs, and
+  all other records.
+- The instance's SSH key pair (`ssh-public.key` and `ssh-private.pem`).
+- The server key pairs.
+- The stored server logs.
+
+:::warning
+The backup contains your instance's private SSH key and the full database. Store it somewhere secure
+and treat it as sensitive.
+:::
+
+## Import
+
+Click **Import** and upload a previously exported zip file to restore it.
+
+:::danger
+Importing **replaces** the current database, SSH keys, key pairs, and server logs with the contents
+of the backup. It is a full restore, not a merge. Only import into a fresh instance, or one whose
+current data you are intentionally overwriting.
+:::
+
+:::info
+Because the instance's SSH key pair is part of the backup, an imported instance keeps the same keys
+and can continue to connect to your existing servers without re-adding them.
+:::

content/docs/4.x/admin/github-app.md

@@ -0,0 +1,114 @@
+# GitHub App
+
+## Introduction
+
+The GitHub App page lets you register a GitHub App for your Vito instance. A GitHub App is a more
+secure way to connect source control than personal access tokens or deployment keys: it uses
+short-lived, per-repository tokens and lets organizations install it to grant access to their
+repositories.
+
+Once registered, GitHub App installations appear as [source controls](/docs/4.x/settings/source-controls)
+that your sites can deploy from.
+
+:::info
+**GitHub App deployments no longer use deployment keys.** Instead of adding an SSH deploy key to each
+repository, Vito injects a short-lived (1 hour), per-repository token at deploy time. The token only
+exists in the environment during the deployment and is never written to disk.
+:::
+
+## Registering the app
+
+You register the app once per Vito instance, using one of two methods.
+
+### Automatic registration
+
+Vito generates a GitHub App manifest and hands off to GitHub, which creates the app and returns its
+credentials (ID, private key, webhook secret) automatically. This is the easiest method and sets up
+webhooks so installs and uninstalls are detected instantly.
+
+:::warning
+Automatic registration relies on GitHub being able to reach your instance via webhooks, so it only
+works when Vito is **publicly accessible on the internet**.
+:::
+
+### Manual registration
+
+For instances that are not publicly reachable (for example, local or private installations, or hosts
+on `.test` / `.localhost` domains), Vito guides you through creating the app manually on GitHub and
+entering its details. This works without public access, but webhook-driven updates will not function
+(see [Keeping installations in sync](#keeping-installations-in-sync)).
+
+Open **Admin > GitHub App**, select the **Manual** tab, and follow the two steps.
+
+#### Step 1: Create the app on GitHub
+
+Click **Open GitHub App creation page** to open GitHub's "Register new GitHub App" form in a new tab.
+Vito displays a set of copyable values to paste into the matching fields on GitHub:
+
+| Vito field                      | Where it goes on GitHub | Notes                              |
+| ------------------------------- | ----------------------- | ---------------------------------- |
+| **Homepage URL**                | Homepage URL            |                                    |
+| **Callback URL**                | Callback URL            |                                    |
+| **Setup URL (post installation)** | Setup URL              | Tick **Redirect on update**        |
+| **Webhook URL**                 | Webhook URL             | Leave **Active** checked           |
+| **Webhook secret**              | Webhook secret          | Generated by Vito; paste it in. The same value is pre-filled in Step 2. |
+
+Set the following **permissions and events**:
+
+- **Repository → Contents**: Read-only
+- **Repository → Metadata**: Read-only (auto-selected by GitHub)
+- **Subscribe to events**: Push
+- **Where can this GitHub App be installed?**: Any account (required so it can be installed on
+  organizations)
+
+:::info
+The **Installation** and **Installation repositories** events are delivered automatically to every
+GitHub App that has a webhook URL. They are not in the "Subscribe to events" list and do not need to
+be selected. Vito uses them to keep installed accounts and repositories in sync.
+:::
+
+After saving the app, on its settings page:
+
+1. Generate a **Client secret**.
+2. Scroll to **Private keys** and **Generate a private key** (GitHub downloads a `.pem` file).
+3. Note the **App ID** shown at the top of the page, and the app's **page URL** from the address bar
+   (for example `https://github.com/apps/vito-yourhost`).
+
+#### Step 2: Paste the credentials into Vito
+
+Back on the GitHub App page in Vito, fill in the form with the values from Step 1 and save:
+
+- **App ID** - the numeric App ID from the app's settings page.
+- **Display name** (optional) - a friendly name for the app.
+- **App page URL** - for example `https://github.com/apps/your-slug`.
+- **Client ID** - from the app's settings page.
+- **Client secret** - the client secret you generated.
+- **Webhook secret** - pre-filled with the value from Step 1; leave it as-is unless you used a
+  different value on GitHub.
+- **Private key (PEM)** - paste the entire contents of the downloaded `.pem` file (including the
+  `-----BEGIN ... PRIVATE KEY-----` lines).
+
+Click **Save GitHub App**. Once saved, the app is configured and you can install it on a GitHub
+organization and sync its installations, just as with automatic registration.
+
+## Connecting repositories
+
+After the app is registered, organizations and users install it on GitHub and choose which
+repositories to grant access to. Each installation is imported into Vito as a source control record,
+and its repositories and branches become available when creating or deploying sites.
+
+## Keeping installations in sync
+
+When Vito is publicly reachable, webhook events keep installations up to date in real time. Vito also
+runs a background sync every 4 hours to reconcile its records with GitHub.
+
+:::info
+If your instance is not publicly reachable, a warning is shown on the page. Installs and uninstalls
+are then only picked up on the 4-hour sync, or when you click the **Sync** button manually.
+:::
+
+## Removing the app
+
+You can remove the GitHub App from Vito. GitHub App source controls cannot be deleted from within
+Vito directly while installed; uninstall the app from GitHub instead, and Vito will reconcile the
+change.

content/docs/4.x/admin/plugins.md

@@ -0,0 +1,42 @@
+# Plugins
+
+## Introduction
+
+The Plugins page in the admin area is where you install and manage plugins for your Vito instance.
+Plugins extend Vito with new providers, services, site types, features, and more.
+
+:::info
+This page covers managing plugins from the admin area. To build your own plugin, see the
+[Plugin development guide](/docs/4.x/plugins).
+:::
+
+## Browsing and installing
+
+From **Admin > Plugins**, the **Official** and **Community** tabs let you browse available plugins.
+Official plugins are developed and maintained by the Vito team; community plugins are contributed by
+the community. Click install on a plugin to add it to your instance.
+
+## Enabling and disabling
+
+Installed plugins appear in the **Installed** tab. A plugin must be **enabled** before Vito boots it.
+Use the menu on each plugin to:
+
+- **Enable** - start booting the plugin so its features become available.
+- **Disable** - stop booting the plugin. Its code stays in your instance and can be re-enabled later.
+- **Uninstall** - remove the plugin's code from your instance entirely.
+
+## Discovering local plugins
+
+If you are developing a plugin locally, the **Discover** tab lists plugins found in your instance's
+plugin directory so you can install them. See the
+[Plugin development guide](/docs/4.x/plugins#local-setup) for details.
+
+## Updating plugins
+
+Click **Check for updates** to see whether any installed plugins have a newer release. When an update
+is available, you can update the plugin from its menu.
+
+## Errors
+
+If a plugin throws an error while booting, Vito disables it automatically and shows the error in this
+page. You can view the error logs for a plugin to debug it.

content/docs/4.x/admin/terminal.md

@@ -0,0 +1,88 @@
+# Terminal
+
+## Introduction
+
+Some of your Vito instance can be managed from the command line. These commands are run on the Vito
+host itself, from the project root (for example `/home/vito/vito`). For the Docker version, run them
+inside the container.
+
+## Clear Logs
+
+Delete all server logs from the database.
+
+```bash
+php artisan logs:clear
+```
+
+## Create User
+
+Create a new user for your Vito instance. The role defaults to `admin`.
+
+```bash
+php artisan user:create [name] [email] [password] [--role=admin]
+```
+
+## Delete older metrics
+
+Delete older monitoring metrics from the database to keep it lean.
+
+```bash
+php artisan metrics:delete-older-metrics
+```
+
+## Generate SSH Keys
+
+Vito has a default public/private SSH key pair created on installation. These keys are used to
+connect to Custom servers to authenticate, and are then removed from the target server. You can
+re-generate them if needed.
+
+```bash
+php artisan ssh-key:generate {--force}
+```
+
+The keys are located in the `storage` directory.
+
+:::warning
+Always keep a backup of your existing keys before running this command. Servers connected with the
+old keys will no longer be reachable once the keys change.
+:::
+
+## Maintenance commands
+
+Vito runs a number of background tasks on a schedule (for example checking server connections,
+collecting metrics, and renewing certificates). You normally never need to run these yourself, but it
+can be useful to trigger one manually, for example to force an immediate check rather than waiting for
+the next scheduled run.
+
+### Check server connections
+
+Re-check the SSH connection status of all servers.
+
+```bash
+php artisan servers:check
+```
+
+### Check for server updates
+
+Check each server for available OS package updates.
+
+```bash
+php artisan servers:check-updates
+```
+
+### Check pending domains
+
+Check DNS resolution for hosted domains that are still pending, activating any that now resolve.
+
+```bash
+php artisan domains:check-pending
+```
+
+### Sync GitHub App installations
+
+Reconcile your local GitHub App source controls with the installations on GitHub. This is the same
+action as the **Sync** button on the [GitHub App](/docs/4.x/admin/github-app) page.
+
+```bash
+php artisan github-app:sync
+```

content/docs/4.x/admin/users.md

@@ -0,0 +1,34 @@
+# Users
+
+## Introduction
+
+The Users page in the admin area lets you manage who can log in to your Vito instance. You can
+create, edit, and delete users, and assign each a role.
+
+## Roles
+
+Each user has one of two roles:
+
+- **Admin** - full access to the instance, including the admin area (users, plugins, GitHub App,
+  and export/import).
+- **User** - standard access to manage the servers and sites within the projects they belong to,
+  without access to the admin area.
+
+## Creating a user
+
+From **Admin > Users**, create a user by providing:
+
+- **Name**
+- **Email** - used to log in.
+- **Password**
+- **Role** - User or Admin.
+
+## Editing and deleting users
+
+You can edit a user to change their details or role, or delete a user that should no longer have
+access.
+
+:::info
+You can also create users from the command line with `php artisan user:create`. See
+[Terminal](/docs/4.x/admin/terminal#create-user).
+:::