diff --git a/.gitignore b/.gitignore index e6ce5a4..e703eb9 100644 --- a/.gitignore +++ b/.gitignore @@ -34,3 +34,5 @@ pnpm-debug.log* # typescript *.tsbuildinfo next-env.d.ts + +.idea/* diff --git a/content/docs/4.x/admin.md b/content/docs/4.x/admin.md deleted file mode 100644 index 93047df..0000000 --- a/content/docs/4.x/admin.md +++ /dev/null @@ -1,66 +0,0 @@ -# Admin - -## Introduction - -You can manage some of the features of your Vito instance from its admin area and some others from the server terminal. - -## Admin Area - -The following features can be managed in the admin area: - -### Users - -Vito allows you to manage users from the admin area. You can create, edit, delete users and also assign roles to them. - -### Export and Import - -You can export and import everything that Vito has stored including servers and logs using the Export and Import feature in the admin area. This is useful when you want to migrate to another Vito instance or create a backup of your current Vito instance. - -### Plugins - -You can manage Vito plugins from the admin area. You can install, activate, deactivate and delete plugins. - -Read more about plugins in the [Plugins Documentation](./plugins.md). - -## Terminal - -Vito ships some cli commands that you can use to manage your Vito instance from the terminal. You can see the list of available commands by running: - -### Clear Logs - -Running the following command will clear/delete all server logs from the server. - -```bash -php artisan logs:clear -``` - -### Create User - -This command will create a new user for your Vito instance. - -```bash -php artisan user:create [name] [email] [password] [--role=admin] -``` - -### Delete older metrics - -This command will delete older monitoring metrics from the database. - -```bash -php artisan metrics:delete-older-metrics -``` - -### Generate SSH Keys - -Vito has default set of a public and private SSH keys when you install it. The keys are basically being used to connect to the Custom server types to authenticate and then they are being deleted from the target server. You have the option to re-generate these keys. - -```bash -php artisan ssh-key:generate {--force} -``` - -The keys are located at `storage` directory. - -:::warning -Make sure you always have a backup of existing keys before running this command. -::: - diff --git a/content/docs/4.x/admin/export-import.md b/content/docs/4.x/admin/export-import.md new file mode 100644 index 0000000..ec8b58f --- /dev/null +++ b/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. +::: diff --git a/content/docs/4.x/admin/github-app.md b/content/docs/4.x/admin/github-app.md new file mode 100644 index 0000000..6de5398 --- /dev/null +++ b/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. diff --git a/content/docs/4.x/admin/plugins.md b/content/docs/4.x/admin/plugins.md new file mode 100644 index 0000000..309e4f4 --- /dev/null +++ b/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. diff --git a/content/docs/4.x/admin/terminal.md b/content/docs/4.x/admin/terminal.md new file mode 100644 index 0000000..7577553 --- /dev/null +++ b/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 +``` \ No newline at end of file diff --git a/content/docs/4.x/admin/users.md b/content/docs/4.x/admin/users.md new file mode 100644 index 0000000..547cfbd --- /dev/null +++ b/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). +::: diff --git a/content/docs/4.x/domains.md b/content/docs/4.x/domains.md index d322114..744a5aa 100644 --- a/content/docs/4.x/domains.md +++ b/content/docs/4.x/domains.md @@ -1,5 +1,10 @@ # Domains +:::info +This page is about managing a domain's **DNS records** through a connected DNS provider. To attach +domains to a specific site and manage their SSL, see [Site Domains](./sites/domains.md). +::: + ## Introduction One of the most frequent actions you need to do when deploying a new website on a new server is to point your domain to that server. For that you need to login to your domain registrar or DNS provider and change the NS records of that domain to point to your server's IP address. diff --git a/content/docs/4.x/getting-started/configuration.md b/content/docs/4.x/getting-started/configuration.md index 3dc1f3d..63b82a9 100644 --- a/content/docs/4.x/getting-started/configuration.md +++ b/content/docs/4.x/getting-started/configuration.md @@ -49,4 +49,61 @@ To force HTTPS on your Vito instance, you need to set the `FORCE_HTTPS` environm FORCE_HTTPS=true ``` -This will activate the `URL::forceScheme('https')` or `URL::forceHttps()` in the Laravel application, ensuring that all URLs generated by the application use HTTPS. \ No newline at end of file +This will activate the `URL::forceScheme('https')` or `URL::forceHttps()` in the Laravel application, ensuring that all URLs generated by the application use HTTPS. + +## Realtime WebSocket + +In v4.x Vito uses a built-in WebSocket server to push live updates to the UI. It works out of the +box, but the following environment variables let you configure and harden it. + +### WS_BROADCAST_SECRET (recommended) + +`WS_BROADCAST_SECRET` is the secret used to authenticate broadcasts to the WebSocket server. If it is +not set, Vito falls back to `APP_KEY` and logs a deprecation warning. + +Setting a dedicated secret is recommended so your `APP_KEY` is not reused for broadcasting (which +reduces the risk of it leaking through logs or monitoring tools). Set it to a long random string: + +```dotenv +WS_BROADCAST_SECRET={A-LONG-RANDOM-STRING} +``` + +You can generate one with: + +```sh +openssl rand -base64 32 +``` + +### WS_ALLOWED_ORIGINS + +`WS_ALLOWED_ORIGINS` is a comma-separated list of origins allowed to connect to the WebSocket server, +used to prevent cross-site WebSocket hijacking. It defaults to your `APP_URL`. + +```dotenv +WS_ALLOWED_ORIGINS="${APP_URL}" +``` + +### WS_URL + +Set `WS_URL` if the WebSocket endpoint the browser connects to differs from your `APP_URL`, for +example during local development. + +```dotenv +WS_URL=http://localhost +``` + +### WS_HOST and WS_PORT + +These control the address the WebSocket server binds to on the host. They default to `127.0.0.1` and +`8085` respectively, and usually do not need changing. + +:::info +After changing any of these values, apply the changes by running the following inside the project +root (or restart/re-create the container for the Docker version): + +```sh +php artisan optimize:clear +php artisan optimize +sudo supervisorctl restart worker:* +``` +::: \ No newline at end of file diff --git a/content/docs/4.x/getting-started/installation.mdx b/content/docs/4.x/getting-started/installation.mdx index f0d31f1..6d954c8 100644 --- a/content/docs/4.x/getting-started/installation.mdx +++ b/content/docs/4.x/getting-started/installation.mdx @@ -4,6 +4,13 @@ Vito provides a single docker image that you can install it easily! +:::info +`WS_BROADCAST_SECRET` is optional but **recommended for production**. It is used to authenticate +realtime WebSocket broadcasts. If you do not set it, Vito falls back to `APP_KEY` and logs a +deprecation warning. See [Configuration](./configuration#ws_broadcast_secret-recommended) for +details. +::: + ### Docker Command ```sh @@ -14,6 +21,7 @@ docker run -v vito_storage:/var/www/html/storage \ -e EMAIL=admin_email \ -e PASSWORD=admin_password \ -e APP_URL=http://your-vito-url \ + -e WS_BROADCAST_SECRET=your_websocket_secret \ -p 80:80 vitodeploy/vito:latest ``` @@ -48,6 +56,7 @@ services: EMAIL: 'vito@example.com' PASSWORD: 'password' APP_URL: 'http://localhost:8000' # Change this to your Vito URL + WS_BROADCAST_SECRET: 'your-websocket-secret' # Optional, recommended for production volumes: - 'vito-storage:/var/www/html/storage' - 'vito-plugins:/var/www/html/app/Vito/Plugins' @@ -59,14 +68,14 @@ volumes: ``` :::info -`:latest` tag is the latest release of VitoDeploy from the `3.x` branch, which is stable and recommended for production use. +`:latest` tag is the latest release of VitoDeploy from the `4.x` branch, which is stable and recommended for production use. -However, if you would like to use the latest code on the `3.x` branch, you may change the image to `vitodeploy/vito:3.x`. +However, if you would like to use the latest code on the `4.x` branch, you may change the image to `vitodeploy/vito:4.x`. ::: ### ARM based images -For arm based architectures, you may add `-arm64` to the image name. For example, `vitodeploy/vito:3.x-arm64` +For arm based architectures, you may add `-arm64` to the image name. For example, `vitodeploy/vito:4.x-arm64` ### Environment Variables @@ -82,6 +91,12 @@ For arm based architectures, you may add `-arm64` to the image name. For example `APP_URL`: The URL of your Vito instance, It is required for some features like Vito Logs to work properly. +:::info +`WS_BROADCAST_SECRET` is optional but **recommended for production**. +::: + +`WS_BROADCAST_SECRET`: A secret used to authenticate realtime WebSocket broadcasts. If unset, Vito falls back to `APP_KEY` and logs a deprecation warning. See [Configuration](./configuration#ws_broadcast_secret-recommended). + ## Install on VPS Vito can be installed on a **fresh** Ubuntu server with only one single command. @@ -106,7 +121,7 @@ You cannot use Vito to install applications into the same server as Vito. Otherw Login to the `root` user of your server via SSH and run the following command: ```sh -bash <(curl -Ls https://raw.githubusercontent.com/vitodeploy/vito/3.x/scripts/install.sh) +bash <(curl -Ls https://raw.githubusercontent.com/vitodeploy/vito/4.x/scripts/install.sh) ``` :::warning diff --git a/content/docs/4.x/getting-started/introduction.mdx b/content/docs/4.x/getting-started/introduction.mdx index b0b48cc..2e20a80 100644 --- a/content/docs/4.x/getting-started/introduction.mdx +++ b/content/docs/4.x/getting-started/introduction.mdx @@ -1,6 +1,6 @@ # Introduction -Vito is a powerful, open-source server management tool designed to simplify the deployment and management of PHP applications. It provides a user-friendly interface for developers and system administrators to automate server provisioning, application deployment, and maintenance tasks. +Vito is a powerful, open-source server management tool designed to simplify the deployment and management of web applications. With first-class support for PHP and Laravel, as well as Node.js and Bun applications, it provides a user-friendly interface for developers and system administrators to automate server provisioning, application deployment, and maintenance tasks. Here are a list of features that Vito provides: @@ -22,12 +22,17 @@ Features available for the databases: ## Application -Vito simplifies the deployment of web applications specifically PHP by automating the process creating virtual hosts, configuring web servers, cloning repositories, and setting up environment variables. +Vito simplifies the deployment of web applications by automating the process of creating virtual +hosts, configuring web servers, cloning repositories, and setting up environment variables. It +supports PHP and Laravel sites, as well as Node.js and Bun applications served via reverse proxy. Features available for the websites: -- Deployments -- SSL +- Deployments, including resuming failed installations +- Hosted domains (multiple alias and redirect domains per site, with DNS validation) +- SSL, including wildcard certificates +- HTTP basic authentication +- Site Tooling (per-site runtimes and package managers) - Supervisor Workers - Commands - Environment Variables @@ -38,7 +43,9 @@ Vito allows you to manage your server's firewall rules easily. You can add, remo ## Programming Languages -You can install and manage multiple versions of PHP and Node.js on your server. Vito supports various versions of these languages, allowing you to run applications that require different versions. +You can install and manage multiple versions of PHP on your server, allowing you to run applications +that require different versions. JavaScript runtimes and package managers such as Node.js, Bun, Yarn, +and pnpm are managed per site through [Site Tooling](/docs/4.x/sites/site-tooling). ## Cron Jobs @@ -56,9 +63,11 @@ Vito is a service oriented server management tool, which means you most of the f Vito provides monitoring capabilities to keep track of your server's performance and resource usage. You can monitor CPU, memory, disk usage to ensure your server is running smoothly. -## Headless Console +## Console -You can directly run commands on your server using the headless console feature. This allows you to execute commands without needing to SSH into the server, making it easier to manage your server from the Vito interface. +Vito includes a full, interactive terminal for your server, right in the browser. It opens a live SSH +shell so you can run commands, install packages, and use interactive programs without opening your own +SSH client. ## Plugins diff --git a/content/docs/4.x/getting-started/securing.md b/content/docs/4.x/getting-started/securing.md index c48519a..733e331 100644 --- a/content/docs/4.x/getting-started/securing.md +++ b/content/docs/4.x/getting-started/securing.md @@ -87,6 +87,30 @@ proxy_buffers 4 256k; proxy_busy_buffers_size 256k; ``` +In v4.x Vito uses a WebSocket server for its live console and realtime updates. When Vito is behind a +reverse proxy, you must also forward the `/ws/` path to the WebSocket server with the upgrade headers, +otherwise the live console and live updates will not work: + +```nginx +location /ws/ { + proxy_pass http://127.0.0.1:8085; + proxy_http_version 1.1; + proxy_set_header Upgrade $http_upgrade; + proxy_set_header Connection "upgrade"; + proxy_set_header Host $host; + proxy_set_header X-Real-IP $remote_addr; + proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; + proxy_read_timeout 86400; +} +``` + +:::info +The WebSocket server listens on `127.0.0.1:8085` by default (configurable via `WS_HOST` and +`WS_PORT`). Make sure `APP_URL` is set to the domain you access Vito on, as `WS_ALLOWED_ORIGINS` +defaults to it. See [Configuration](./configuration#realtime-websocket) for the related environment +variables. +::: + ### Update environment variables Now you need add/update the following variables in the `.env` file if you are using VPS installation or docker's environment variables if you are using docker: diff --git a/content/docs/4.x/getting-started/update.md b/content/docs/4.x/getting-started/update.md index dcd827a..04712f1 100644 --- a/content/docs/4.x/getting-started/update.md +++ b/content/docs/4.x/getting-started/update.md @@ -2,32 +2,6 @@ ## Update VPS -If you've installed VitoDeploy on a linux virtual machine, To update it to the latest version you just need to run the -`update.sh` file inside the root of the project. - -:::warning -Make sure you SSH to your Vito server via `vito` user. If you logged in via the `root` user then change it to `vito` ( -`su vito`) -::: - -```sh -cd /home/vito/vito - -bash scripts/update.sh -``` - -If the above command didn't update your VitoDeploy to the latest version, You can try the following commands: - -```sh -git stash -git clean -f -bash scripts/update.sh -``` - -:::info -To get the `alpha` or `beta` releases of VitoDeploy you can simply pass `--alpha` or `--beta` flags to the update script. -::: - ## Update Docker If you've installed VitoDeploy on a docker container, You just need to pull the latest version and recreate the diff --git a/content/docs/4.x/plugins.md b/content/docs/4.x/plugins.md index 7f11fc5..bb2137c 100644 --- a/content/docs/4.x/plugins.md +++ b/content/docs/4.x/plugins.md @@ -17,6 +17,15 @@ Plugins can change or extend the following features: - **Services**: Add new services or modify existing ones. - **Site Types**: Add new site types or modify existing ones. - **Site Features**: Add new site features or modify existing ones. +- **Server Features**: Add new server features or modify existing ones. +- **Workflow Actions**: Add new actions that can be used in workflows. +- **Console Commands & Views**: Register console commands and views used by your plugin. + +:::warning +If you are upgrading a plugin from 3.x, several provider contracts changed in v4.x, most notably for +**Site Types** and **Web Server** services. Review the +[plugin breaking changes](/docs/4.x/prologue/breaking-changes#plugins) before upgrading. +::: ## Installing and Managing Plugins @@ -142,9 +151,49 @@ Use `App\Plugins\RegisterSiteType` to register a new site type using the `boot` The `handler` method should point to a class that extends `App\SiteTypes\AbstractSiteType` or implements `App\SiteTypes\SiteType`. +#### Site type contract (v4.x) + +In v4.x the vhost rendering model changed: instead of returning markup, a site type points at a +template and supplies data to it. The `SiteType` interface now requires: + +```php +public function vhostData(): array; // data passed to the vhost template +public function supportedWebservers(): ?array; // null = all webservers +public function vhostTemplate(string $webserver): ?string; +public function deploymentEnvironment(): array; // extra env vars for deploys/commands +public function afterDeploy(Deployment $deployment): void; +public function defaultDeploymentScript(): string; +``` + +If you extend `AbstractSiteType`, defaults are provided for all of these, so existing plugins will +not fatal. The old `vhost(string $webserver)` method has been removed, so move your markup into a +[Mustache](https://mustache.github.io) template and return its name from `vhostTemplate()`, supplying +variables via `vhostData()`. By default `defaultDeploymentScript()` reads +`resources/deployment-scripts/{id}.sh`. + +The protected `progress()` helper signature also changed to `progress(int $percentage, ?string $step)`. + +Optional tooling hooks let a site type declare the [Site Tooling](/docs/4.x/sites/site-tooling) it +needs: `static supportsTooling(): bool`, `static requiredTooling(): array`, and +`static createTimeTools(): array`. + +:::info +For reverse proxy site types (such as Node and Bun), extend `App\SiteTypes\AbstractProxiedSiteType`, +which provides the port, start command, and worker handling described in +[Application](/docs/4.x/sites/application#reverse-proxy-sites). +::: + :::info -You can find some of the built-in site types are -in [Site Types](https://github.com/vitodeploy/vito/tree/3.x/app/SiteTypes) +You can find some of the built-in site types +in [Site Types](https://github.com/vitodeploy/vito/tree/4.x/app/SiteTypes) +::: + +:::warning +Site identity attributes are now relation-backed via the isolated user. `$site->user` and +`$site->ssh_key` are accessors that may resolve from a shared `IsolatedUser`, and FPM pools and users +can be shared across sibling sites. See the +[plugin breaking changes](/docs/4.x/prologue/breaking-changes#isolated-users) if your plugin touches +these. ::: ### Register site features and actions @@ -313,6 +362,17 @@ that service type. For example, If you develop a web server service, you will need to implement the `App\Services\Webserver\Webserver` interface or extend the `App\Services\Webserver\AbstractWebserver` class. +:::warning +In v4.x the web server contract changed. `AbstractWebserver` now has two abstract methods you must +implement: `generateVhost(Site $site, ?string $template = null): string` and `deploySplash(): void`. +The `updateVHost()` signature was simplified (the block-manipulation arrays were removed and the +default `$restart` is now `false`), and `changePHPVersion()` was removed entirely. New SSL-related +methods (`createsSiteSSLs()`, `siteDefaults()`, `canConfigureSSL()`, `allowedSslMethods()`, +`defaultSslMethod()`) have safe defaults on `AbstractWebserver`. See the +[plugin breaking changes](/docs/4.x/prologue/breaking-changes#web-server-services) for the full +detail. +::: + **Service Config Files** You can register your service's config files using the `configPaths` method. Vito will allow you to modify these files in the Services page. @@ -323,7 +383,7 @@ For a non-listed service types, you can implement the `App\Services\ServiceInter ::: :::info -You can find plenty of examples in the [Services](https://github.com/vitodeploy/vito/tree/3.x/app/Services) +You can find plenty of examples in the [Services](https://github.com/vitodeploy/vito/tree/4.x/app/Services) ::: ### Register server providers @@ -352,7 +412,7 @@ The handler must implement the `App\ServerProviders\ServerProvider` interface or :::info You can find plenty of examples in -the [Server Providers](https://github.com/vitodeploy/vito/tree/3.x/app/ServerProviders) +the [Server Providers](https://github.com/vitodeploy/vito/tree/4.x/app/ServerProviders) ::: ### Register storage providers @@ -380,7 +440,7 @@ The handler must implement the `App\StorageProviders\StorageProvider` interface :::info You can find plenty of examples in -the [Storage Providers](https://github.com/vitodeploy/vito/tree/3.x/app/StorageProviders) +the [Storage Providers](https://github.com/vitodeploy/vito/tree/4.x/app/StorageProviders) ::: ### Register source controls @@ -406,8 +466,23 @@ You can register your own source control provider using `App\Plugins\RegisterSou The handler must implement the `App\SourceControls\SourceControl` interface or extend the `App\SourceControls\AbstractSourceControl` class. +In v4.x the `SourceControlProvider` interface gained four methods: `getSshPort()`, +`static editableFields()`, `editRules(array $input)`, and `editData(array $input)`. Extending +`AbstractSourceControlProvider` provides safe defaults (SSH port 22, no editable fields); implementing +the interface directly means you must add all four. + +The `RegisterSourceControl` builder also accepts `->connectable(bool)` and `->usableForSites(bool)`, +and v4.x ships a built-in GitHub App provider. + +:::danger +If you override `editableFields()` to return a non-empty list, you must also override `editData()` to +whitelist exactly which keys are merged. The default spread would otherwise let callers overwrite +encrypted fields such as `token`. See the +[plugin breaking changes](/docs/4.x/prologue/breaking-changes#source-control-providers). +::: + :::info -You can find plenty of examples in the [Source Controls](https://github.com/vitodeploy/vito/tree/3.x/app/SourceControls) +You can find plenty of examples in the [Source Controls](https://github.com/vitodeploy/vito/tree/4.x/app/SourceControls) ::: ### Register notification channels @@ -435,14 +510,38 @@ The handler must implement the `App\NotificationChannels\NotificationChannel` in :::info You can find plenty of examples in -the [Notification Channels](https://github.com/vitodeploy/vito/tree/3.x/app/NotificationChannels) +the [Notification Channels](https://github.com/vitodeploy/vito/tree/4.x/app/NotificationChannels) ::: ### Register Workflow Actions [Workflows](./workflows.md) can be extended by adding new actions. You can register your own workflow action using `App\Plugins\RegisterWorkflowAction` in the `boot` method of your `Plugin.php` file. -You can find handful examples of workflow actions in the [Workflow Actions](https://github.com/vitodeploy/vito/tree/3.x/app/WorkflowActions) +You can find handful examples of workflow actions in the [Workflow Actions](https://github.com/vitodeploy/vito/tree/4.x/app/WorkflowActions) + +### Tooling providers + +v4.x introduces [Site Tooling](/docs/4.x/sites/site-tooling), which installs developer runtimes and +package managers (such as Node, Bun, Yarn, and pnpm) for a site's isolated user. + +A tooling provider implements `App\Tooling\ToolingInterface`, or extends `App\Tooling\AbstractTooling` +(or `App\Tooling\AbstractMiseTooling` for runtimes managed by Mise). Providers are registered through +the `tooling.providers` config array: + +```php +config([ + 'tooling.providers' => array_merge( + config('tooling.providers', []), + [YourTooling::class], + ), +]); +``` + +:::info +There is no dedicated `RegisterTooling` plugin builder yet; tooling providers are registered via +config. You can find the built-in providers in +[Tooling](https://github.com/vitodeploy/vito/tree/4.x/app/Tooling). +::: ### Events @@ -480,12 +579,17 @@ Dynamic fields are a set of input fields designed to collect inputs from the act Here are the list of supported fields: -- Label - Text field +- Password field (with an optional show/hide toggle) +- Textarea - Checkbox - Select field - Alert (with types: info, warning, error, success) - Link +- Component (render a custom frontend component) + +v4.x also adds tooling-aware fields for use with [Site Tooling](/docs/4.x/sites/site-tooling), such as +a tooling picker and selector. For more details, check `App\DTOs\DynamicField::class` diff --git a/content/docs/4.x/prologue/breaking-changes.md b/content/docs/4.x/prologue/breaking-changes.md new file mode 100644 index 0000000..a275340 --- /dev/null +++ b/content/docs/4.x/prologue/breaking-changes.md @@ -0,0 +1,192 @@ +# Breaking Changes + +## Custom VHost Configuration + +In v4.x the vhost template engine changed from **Blade** to +[**Mustache**](https://mustache.github.io). If you have customised the default vhost template, your +existing customisations will not carry over, and any Blade syntax (`@if`, `{{ $variable }}`, etc.) +will no longer be interpreted. See the [Mustache manual](https://mustache.github.io/mustache.5.html) +for the new syntax. + +:::warning +To avoid breaking live sites during the upgrade, vhost generation is **disabled by default on every +existing site**. Each site needs you to review and enable the new template before Vito will +regenerate its vhost. +::: + +For each site, open its **Settings** page to see the current vhost alongside a **preview** of the +new Mustache-generated output. Once you are happy that the new template produces the configuration +you expect, enable it to switch the site over. + +## NodeJs Sites + +The original **NodeJs** site type is now **deprecated**. Existing NodeJs sites will continue to work, +but the type can no longer be used to create new sites. + +Use the new **Node** site type instead. It uses [Site Tooling](/docs/4.x/sites/site-tooling) to +manage Node versions and any other tools your site needs, rather than baking the version into the +site type. + +There is no automated migration from the deprecated type to the new one. If you want the new +features on an existing NodeJs site, you will need to migrate it manually. + +## VitoAgent updated + +The `vitoagent` service has been updated for v4.x, and if you are running this, you will need to update it +via the services for each server. You can do this easily by uninstalling and reinstalling the VitoAgent on each +server it's currently installed on. + +:::info +Where a VitoAgent is not updated on a given server, certain monitoring statistics will appear empty of have no value +and restart monitoring of the server will not function. +::: + +## Plugins + +If you maintain a Vito plugin, these are the contract changes you need to be aware of in v4.x. The +plugin registration API (`App\Plugins\Register*` builders, `AbstractPlugin`, `PluginInterface`) and +the core `ServiceInterface` / `AbstractService` base classes are **unchanged**. Every breaking +change below lives in the contracts that specific provider types extend. + +:::info +**Who this affects:** plugins registering a **Site Type**, **Web Server** service, or **Source +Control** provider. Plugins that only register Server providers, Storage providers, DNS providers, +Notification channels, Workflow actions, Server/Site features, or Commands are unaffected. +::: + +### At a glance + +| Your plugin registers... | Action needed | +| -------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- | +| Site type | **Yes** - move `vhost()` to `vhostTemplate()` + `vhostData()`; fix the `progress()` signature | +| Web server | **Yes** - implement `generateVhost()` + `deploySplash()`; update `updateVHost()`; drop `changePHPVersion()` | +| Source control | Only if you implement the interface directly (not via the abstract) | +| Anything reading `$site->user` / `$site->ssh_key` / FPM pools | **Review** - these are now isolated-user-backed | +| Server provider, Storage, DNS, Notifications, Workflow, Features, Commands | None | + +### Site Types + +The `App\SiteTypes\SiteType` interface was reworked. The vhost rendering model changed from "return +markup" to "point at a template and supply data". + +**Removed** + +```php +// GONE from the SiteType interface +public function vhost(string $webserver): string|View; +``` + +**Added** (required on the interface): + +```php +public function vhostData(): array; // data passed to the vhost template +public function supportedWebservers(): ?array; // null = all +public function vhostTemplate(string $webserver): ?string; +public function deploymentEnvironment(): array; +public function afterDeploy(Deployment $deployment): void; +public function defaultDeploymentScript(): string; +``` + +#### Migration + +- Move your markup into a Blade template, return its name from `vhostTemplate()`, and supply + variables via `vhostData()`. +- `defaultDeploymentScript()` now defaults to reading `resources/deployment-scripts/{id}.sh`. +- The protected `progress()` signature changed from `progress(int $percentage)` to + `progress(int $percentage, ?string $step)`. Overrides or callers must add the `$step` argument. It + now also broadcasts a `site.updated` socket event and writes the new `progress_step` column. + +:::warning +If you extend `AbstractSiteType` you will **not** get a fatal error, because the abstract supplies +defaults for all six new methods. But your old `vhost()` method becomes dead code that is never +called, so your site's vhost silently falls back to defaults until you migrate it. +::: + +New optional tooling hooks (default to "no tooling"): `static createTimeTools(): array`, +`static requiredTooling(): array`, `static supportsTooling(): bool`. + +### Web Server services + +The `App\Services\Webserver\Webserver` interface changed significantly, and `AbstractWebserver` +gained two new abstract methods you must implement (or you get a fatal error): + +```php +abstract public function generateVhost(Site $site, ?string $template = null): string; +abstract public function deploySplash(): void; +``` + +The `updateVHost()` signature changed, dropping the block-manipulation arrays. Note the default +`$restart` also flipped from `true` to `false`, and the protected helper `getUpdatedVHost()` was +removed. + +```php +// 3.x +public function updateVHost(Site $site, ?string $vhost = null, array $replace = [], array $regenerate = [], array $append = [], bool $restart = true): void; +// v4.x +public function updateVHost(Site $site, ?string $vhost = null, bool $restart = false): void; +``` + +`changePHPVersion(Site $site, string $version): void` was **removed** from the interface and the +entire codebase. PHP-version changes are no longer driven through the web server. + +New SSL-related interface methods (defaults provided by `AbstractWebserver`, so extending it is +safe): `createsSiteSSLs()`, `siteDefaults()`, `canConfigureSSL()`, `allowedSslMethods()`, +`defaultSslMethod()`. These back a reworked SSL system using a new `App\Enums\SslMethod` enum and a +new `SslType::CSR` case. `createsSiteSSLs()` reads the `creates_site_ssls` flag from your service's +data config. + +### Source Control Providers + +The `SourceControlProvider` interface gained four new methods; `AbstractSourceControlProvider` +supplies safe defaults (SSH port 22, no editable fields). + +```php +public function getSshPort(): int; +public static function editableFields(): array; +public function editRules(array $input): array; +public function editData(array $input): array; +``` + +#### Migration + +- Extend `AbstractSourceControlProvider` and you are safe. +- Implement `SourceControlProvider` directly and you must add all four methods, or you get a fatal + error. + +:::danger +**Security contract:** if you override `editableFields()` to return a non-empty list, you must also +override `editData()` to whitelist exactly which keys are merged. The default spread would let +callers overwrite encrypted fields like `token`. +::: + +`RegisterSourceControl` is additive and non-breaking: new `->connectable(bool)` and +`->usableForSites(bool)` builders, and the registry now also emits `connectable`, `usable_for_sites`, +and an auto-derived `editable_fields`. v4.x also ships a built-in GitHub App provider. + +### Isolated Users + +This affects any plugin that touches a Site. v4.x introduces a dedicated `App\Models\IsolatedUser` +model, and the Site's identity attributes are now relation-backed. + +- `$site->user` and `$site->ssh_key` are now accessors that fall back to `$site->isolatedUser`, and + the underlying columns may be null. Reads still work, but writing directly to them no longer + behaves as it did. +- `Site::changePHPVersion()` and `Site::activeSsl()` were removed. +- New helpers: `Site::fpmPoolSharedWithSiblings()`, `userSharedWithSiblings()`, + `siblingsSharingUser()`, `htpasswdPath()`, plus tooling helpers and a `progress_step` column. Site + now eager-loads `isolatedUser` by default. +- FPM pools and the isolated user are now shared across sibling sites of the same user, and isolation + runs under a lock. Plugins that created or assumed one FPM pool per site should account for this. +- `config/core.php` adds a `reserved_user_names` blocklist enforced during site creation. + +### New extension points and built-ins + +These are additive, so no action is required. + +- **Tooling system:** `App\Tooling\ToolingInterface` plus `AbstractTooling` / `AbstractMiseTooling`, + registered via `config('tooling.providers')` (an array of class strings; there is no + `RegisterTooling` plugin builder yet). Built-ins: Node, Bun, Yarn, Pnpm. +- **New built-ins:** SFTP storage provider, Valkey database service, `NodeSite` / `BunSite` site + types, and an `AbstractProxiedSiteType` base class. +- **WebSocket config** moved into `config/core.php` (`ws_host`, `ws_port`, `ws_broadcast_secret`, + `ws_allowed_origins`). The `SocketEvent::dispatch()` API itself is unchanged. \ No newline at end of file diff --git a/content/docs/4.x/prologue/release-notes.md b/content/docs/4.x/prologue/release-notes.md index f0c8577..845784b 100644 --- a/content/docs/4.x/prologue/release-notes.md +++ b/content/docs/4.x/prologue/release-notes.md @@ -1,37 +1,104 @@ # Release Notes -## Migrating to Inertia and React +## Laravel 13 and Inertia v3 -In this release, we have migrated the dashboard to use Inertia.js and React. This change allows for a more dynamic and -responsive user interface, improving the overall user experience. The new setup also enables easier development of -future features and enhancements. +Vito v4.x has been updated to the latest versions: Laravel 13, Inertia.js 3, and Vite 8. This brought +refactors to plugin caching and CSRF middleware, and keeps Vito current with the latest framework +releases. -## New dashboard UI +### Inertia context shrinking -The dashboard has been completely redesigned to provide a more intuitive and user-friendly experience. The new UI -features a cleaner layout, improved navigation, and enhanced visual elements to help users manage their servers -more effectively. +Inertia responses previously shipped ~120 KB+ of mostly-static shared data on every request (the +Ziggy route table, the provider/service catalogue, and more). A new cached bootstrap endpoint now +serves this once and hydrates it on the frontend, cutting typical responses down to a few KB. -## Plugins +## Realtime websocket Updates -Plugins are now supported in Vito, allowing users to extend the functionality of VitoDeploy. Users can now develop and -install official and community supported plugins to add new features or modify existing ones. This opens up a wide range -of possibilities for customization and enhancement of the VitoDeploy experience. +Vito now ships a built-in WebSocket server that pushes live updates across all async operations - +deployments, servers, services, sites, SSLs, backups and more - replacing the old polling-based +refresh. The header shows connection status with manual reconnect, and connections survive page +navigation. -## Background jobs performance improvements +## GitHub App registration -We've migrated the queue system from Laravel's default database queue to Horizon with Redis. Vito's queues were -previously running with only one worker, which caused delays in processing background jobs. Now, with the new setup, -VitoDeploy can handle multiple background jobs simultaneously, significantly improving the performance. +Connect source control via a GitHub App, a more secure alternative to personal access tokens and +deployment keys. Register an app against your instance (automatically or manually), and deployments +authenticate with short-lived, per-repo tokens that never touch disk. -## Export and Import +## Site improvements -The export and import functionality has been added to VitoDeploy, allowing users to easily export and backup their -server configurations and import them when needed. This feature is particularly useful for users who want to -migrate their Vito instance from machine to machine or for those who want to keep a backup of their server settings. +### Resume failed site deployments -## Redis for Caching, Sessions, and Queues +Sites that fail during installation now enter a failed state instead of being lost. A failure banner +surfaces a friendly error summary, and a Retry action resumes the install idempotently from where it +left off. -Vito version 3.x uses Redis for caching, sessions, and queues. This change improves the performance and solves the -Database lock issues with SQLite. Redis is a powerful in-memory data structure store that provides high performance and -scalability for these tasks. \ No newline at end of file +## Shared isolated users + +Isolated users can now be shared across multiple sites on a server rather than being tied to one. +This release adds default username suggestions, distributed locking to prevent race conditions, and +a reserved-name list that blocks system accounts from being used as site users. + +### Hosted domains + +Manage multiple alias and redirect domains per site. Domains that don't yet resolve are held in a +pending state and re-checked automatically (or validated on demand), each domain can have its own SSL +option, and vhost generation is driven by editable nginx/Caddy templates with preview. + +### Site tooling + +Per-site tooling management has been expanded and standardised, with install and uninstall actions. +Tooling now correctly runs as the site's isolated user and is available across all site types, not +just PHP. + +### Site stats (beta) + +Install the new GoAccess service to get per-site traffic statistics. Stats appear per site, refresh +automatically every hour, and can be enabled or disabled individually. + +### Bun & Node site types + +Vito now supports Bun and Node.js sites natively, with per-site version management via Site Tooling. +PHP/Laravel sites can optionally install Node/Bun alongside them where needed. + +### Site Alerts + +Vito now tracks and displays alerts per site, both on the table listings and with more information on each +site page. Multiple alerts collapse automatically, and most provide a call to action. Alerts can include +when domains no longer resolve to the server, VHost generation is turned off, or a Worker has failed to start. + +### HTTP basic auth + +Protect sites with HTTP Basic Authentication on both nginx, Caddy and Apache. This is useful for staging and +preview sites that must be publicly reachable but not openly accessible. Users and passwords are +managed from the site settings UI. + +## Server improvements + +### Service Log viewer + +A new Service Logs section in the server logs menu exposes logs for installed services automatically. +You can change the number of lines shown, download the full file, or clear a log. + +### Monitoring updates + +Server monitoring has been extended to collect and visualize a much wider range of system metrics, +with supporting database, API, and frontend updates. + +### Server Alerts + +Vito now tracks and displays alerts per server, both on the table listings and with more information on each +server page. Multiple alerts collapse automatically, and most provide a call to action. Alerts can include +when a server needs a restart, or when updates to packages are available. + +### Apache support (beta) + +Apache joins nginx and Caddy as a supported webserver. The config generation system was refactored +for extensibility, removing hard-coded webserver assumptions throughout the codebase, Apache joins Vito +in beta, and we would not recommend using on a production server just yet. + +### SSL updates, including wildcard certs + +SSL certificates can now be managed directly at the server level, in addition to per-site. This adds +custom certificates, CSR generation and download, and auto-renewing wildcard Let's Encrypt certificates +for domains managed by Vito. diff --git a/content/docs/4.x/prologue/upgrade.md b/content/docs/4.x/prologue/upgrade.md index 2eafc12..dcf23df 100644 --- a/content/docs/4.x/prologue/upgrade.md +++ b/content/docs/4.x/prologue/upgrade.md @@ -6,203 +6,5 @@ volumes for the docker installations. ::: -## Upgrading to 3.x from 2.x +## Upgrading to 4.x from 3.x -## Upgrade Docker Installation - -If you're using the latest tag, just do the [Update](../getting-started/update#update-docker) steps. - -If you're using the `2.x` tag, You need to change it to `3.x` or `latest` tag. - -:::info -`3.x` tag is the latest code on the `3.x` branch, which might not be stable yet, but it will be soon. - -`latest` tag is the latest release of VitoDeploy from the `3.x` branch, which is stable and recommended for production -use. - -We recommend using the `latest`. -::: - -:::warning -It is required to have `APP_URL` environment variable set to your Vito URL, otherwise, some features like Vito Logs won't work properly. -::: - -## Upgrade VPS Installation - -You can upgrade your Vito instance from 2.x to 3.x in Automatic or Manual mode. - -### Automatic Upgrade - -Run the following command as `vito` user: - -```sh -bash <(curl -Ls https://raw.githubusercontent.com/vitodeploy/vito/3.x/scripts/upgrade-2x-to-3x.sh) -``` - -### Manual Upgrade - -SSH to your Vito instance with user `vito` and continue the steps: - -Go to the root of the project: - -```sh -cd /home/vito/vito -``` - -**Discard all the possible changes to the code base:** - -```sh -git stash -``` - -**Fix any possible ownership change to the code base:** - -```sh -sudo chown -R vito:vito /home/vito/vito -``` - -**Install PHP 8.4:** - -```sh -sudo add-apt-repository ppa:ondrej/php -y -sudo apt update -sudo apt install -y php8.4 php8.4-fpm php8.4-mbstring php8.4-mcrypt php8.4-gd php8.4-xml php8.4-curl php8.4-gettext php8.4-zip php8.4-bcmath php8.4-soap php8.4-redis php8.4-sqlite3 php8.4-intl -sudo sed -i "s/www-data/vito/g" /etc/php/8.4/fpm/pool.d/www.conf -sudo service php8.4-fpm enable -sudo service php8.4-fpm start -sudo apt install -y php8.4-ssh2 -sudo service php8.4-fpm restart -sudo sed -i "s/memory_limit = .*/memory_limit = 1G/" /etc/php/8.4/fpm/php.ini -sudo sed -i "s/upload_max_filesize = .*/upload_max_filesize = 1G/" /etc/php/8.4/fpm/php.ini -sudo sed -i "s/post_max_size = .*/post_max_size = 1G/" /etc/php/8.4/fpm/php.ini -``` - -**Install Redis:** - -Vito version 3.x uses Redis for caching, sessions, and queues. You need to install Redis server on your VPS. - -```sh -sudo apt install redis-server -y -sudo service redis enable -sudo service redis start -``` - -**Install Node.js:** - -Vito v3 uses Inertia.js, which requires Node.js to be installed. - -```sh -curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash - -sudo apt install -y nodejs -``` - -**Adjust the Nginx configuration:** - -Set php-fpm to use PHP 8.4 instead of PHP 8.2 by running the following command: - -```sh -sudo sed -i "s/php8.2-fpm.sock/php8.4-fpm.sock/g" /etc/nginx/sites-available/vito -``` - -Add the following to the `/etc/nginx/sites-available/vito` as well: - -```nginx - location ~ \.php$ { - ... - fastcgi_buffers 16 16k; - fastcgi_buffer_size 32k; - ... - } -``` - -You can run this command instead - -```sh -sudo sed -i '/location ~ \\\.php\$ {/a \ fastcgi_buffers 16 16k;\n fastcgi_buffer_size 32k;' /etc/nginx/sites-available/vito -``` - -:::warning -Make sure to confirm the change by opening the file `/etc/nginx/sites-available/vito` -::: - -Vito v3 transfers more data on the request headers because of the Inertia.js, so you need to increase the `client_max_body_size`. - -Open `/etc/nginx/sites-available/vito` and add `client_max_body_size 100M;` line inside the `server` block. - -This increase is necessary to allow you to export and import larger Vito settings. - -```nginx -server { - ... - client_max_body_size 100M; - ... -} -``` - -Then restart Nginx: - -```sh -sudo service nginx restart -``` - -**Update supervisor configuration** - -Vito now uses [Laravel Horizon](https://laravel.com/docs/12.x/horizon) for managing queues, so you need to update the supervisor configuration. - -You need to update `/etc/supervisor/conf.d/worker.conf` file to use Horizon instead of the worker. - -```sh -sudo sed -i 's/command=php \/home\/vito\/vito\/artisan queue:work --sleep=3 --backoff=0 --queue=default,ssh,ssh-long --timeout=3600 --tries=1/command=php \/home\/vito\/vito\/artisan horizon/' /etc/supervisor/conf.d/worker.conf -``` - -Or do it manually by setting `command` to: - -```sh -command=php /home/vito/vito/artisan horizon -``` - -Then restart the supervisor: - -```sh -sudo service supervisor restart -``` - -**Pull the latest changes:** - -```sh -git fetch -``` - -**Switch to the `3.x` branch:** - -```sh -git checkout 3.x -``` - -**Run the update script:** - -```sh -bash scripts/update.sh -``` - -### Upgrade failed? - -If the upgrade (automatic or manual) failed, follow these steps to fix it: - -1. [Install a new Vito instance](../getting-started/installation.mdx#install-on-vps) -2. Copy the `.env` file from the old instance backup to the new instance. -3. Copy the `storage` folder from the old instance backup to the new instance. -4. Run `bash scripts/update.sh` on the new instance to apply the changes. - -## Upgrade Local installation - -If you're using Laravel Sail, you need to kill the current container and delete its images and then boot sail up again. - -[Read the installation documentation](../getting-started/installation.mdx#laravel-sail) for more information. - -If you're using other tools like Laravel Valet or etc., You need to make sure you have PHP 8.4 installed and then switch -to the `3.x` branch. - -:::warning -Make sure you set the `REDIS_HOST=redis` environment variable in your `.env` file. -::: \ No newline at end of file diff --git a/content/docs/4.x/servers/console.md b/content/docs/4.x/servers/console.md index 5d12983..d8715c1 100644 --- a/content/docs/4.x/servers/console.md +++ b/content/docs/4.x/servers/console.md @@ -1,30 +1,51 @@ -# Headless Console/Terminal +# Console / Terminal ## Introduction -Sometimes you need to run commands on your server to do some tasks like installing packages, updating the system, etc -and you don't want to SSH to the server due to some reasons like security, etc. +The Console is a full, interactive terminal for your server, right in the browser. It is useful for +running commands, installing packages, or inspecting the system without opening your own SSH client. -Headless Console/Terminal is a feature that allows you to run commands on your server remotely via SSH connection. +In v4.x this is a **live terminal**. Vito opens a real interactive SSH shell to the server and streams +it to the browser over a WebSocket, so it behaves like a normal terminal. -## Supported Users +:::info +Unlike earlier versions, the terminal is now **stateful and interactive**. Commands like `cd` carry +over to the next command, and interactive programs (such as `top`, `vim`, or `nano`) work as +expected. +::: + +## Opening the terminal + +Navigate to your server and click the **terminal icon** in the top right corner. The terminal opens +in a new window and connects automatically. -You can run commands on your server remotely via Headless Console with these users: +## Choosing a user -- root -- vito +A user selector at the top of the terminal lets you choose which system user to connect as. The +available users are: -## Run commands +- `root` +- The server's main Vito user (for example `vito`) +- Any [isolated users](/docs/4.x/sites/isolation) on the server +- Any site users + +Switching the user starts a fresh session connected as that user. + +:::info +When you connect as an isolated user, any [Site Tooling](/docs/4.x/sites/site-tooling) installed for +that user is available in the shell. Runtimes and package managers such as `node`, `npm`, `bun`, +`yarn`, and `pnpm` can be used directly, just as they can in [commands](/docs/4.x/sites/commands). +::: -Navigate to your server page and on top right corner you will see a terminal icon, click on it or press `Ctrl + Shift + K` to open the terminal. +## Sessions -Headless Console/Terminal will run the commands on your server via SSH connection from the home directory of the chosen -user. +The terminal connects as soon as it opens. A status indicator next to the server name shows the +connection state (connecting, connected, or error). -After you hit the `Run` button it will open a SSH connection to your server and an open stream to your Vito instance to -print out the output of the command in real time. +To start over, click the **New Session** button (the refresh icon). This closes the current shell and +opens a new one. The terminal also resizes to fit the window. :::warning -The Console/Terminal is stateless! which means every command will run from the home directory of the chosen user and -running something like `cd` and then another command will not go through the new directory. +The terminal runs commands directly on your server as the selected user, with that user's full +permissions. Be careful when connected as `root`. ::: diff --git a/content/docs/4.x/servers/cronjobs.md b/content/docs/4.x/servers/cronjobs.md index bc65df0..b9c7422 100644 --- a/content/docs/4.x/servers/cronjobs.md +++ b/content/docs/4.x/servers/cronjobs.md @@ -30,7 +30,9 @@ Do not add any frequency (`* * * * *`) to the command because VitoDeploy will ad ### User -The cronjob command will be executed by this user +The cronjob command will be executed by this user, which will include any tooling that the user has enabled. `root` and +`vito` users will not have access to tooling installed per site. It's recommended, unless absolutely nessisary, to run +the command as the user of the site it's running against. ### Frequency diff --git a/content/docs/4.x/servers/firewall.md b/content/docs/4.x/servers/firewall.md index 0e1f8c8..0194a91 100644 --- a/content/docs/4.x/servers/firewall.md +++ b/content/docs/4.x/servers/firewall.md @@ -39,7 +39,7 @@ Select the protocol you want to apply the rule to ### Port -Incoming port which you are going to apply the rule to +Incoming port which you are going to apply the rule to, this can be a range, for example; `8000:8100` ### Source diff --git a/content/docs/4.x/servers/logs.md b/content/docs/4.x/servers/logs.md index 3c25e73..e169ce0 100644 --- a/content/docs/4.x/servers/logs.md +++ b/content/docs/4.x/servers/logs.md @@ -10,6 +10,11 @@ You can navigate to the `Logs` page of each server and view its logs. These are the logs stored after each command you run on your server via Vito. +## Service Logs + +These are logs provided by the services you have installed, such as the NGINX error log, or the redis journey entries, +when a new service is installed, if it has any associated logs, they will appear here. + ## Remote Logs Vito enables you to also watch log files existing on your server. You can add the full path for those logs in the Remote Logs section and start watching them. \ No newline at end of file diff --git a/content/docs/4.x/servers/monitoring.md b/content/docs/4.x/servers/monitoring.md index 84cf52e..787b26b 100644 --- a/content/docs/4.x/servers/monitoring.md +++ b/content/docs/4.x/servers/monitoring.md @@ -4,11 +4,23 @@ VitoDeploy enables you to monitor your servers' resource usages like CPU Load, Memory, and Disk usage. -Vito offers 2 ways of monitoring servers. +Vito offers 2 ways of monitoring servers, which differ in how the metrics are collected: + +- **Remote Monitor** - your Vito instance **polls** each server over SSH every minute. +- **VitoAgent** - an agent on each server **pushes** metrics to your Vito instance. + +:::warning +If Vito is managing more than around 8-10 servers, or runs on a lower-specification node, we +recommend using **VitoAgent** rather than Remote Monitor. Because Remote Monitor opens an SSH +connection to every server every minute, the cost grows with each server you add and is borne +entirely by the Vito instance. VitoAgent pushes metrics from each server instead, spreading the work +out and keeping your Vito instance responsive at scale. +::: ## Remote Monitor -If you chose to use the Remote Monitor, Vito will check your servers every minute to extract their resource usages. +If you chose to use the Remote Monitor, Vito will poll your servers over SSH every minute to extract +their resource usages. To install Remote Monitor you just need to go to the Services and hit the Install button on the Remote Monitor service under the Supported Services section. @@ -17,6 +29,11 @@ After the installation was successful, You can navigate to the Metrics page and Keep in mind that it will take a couple of minutes to collect enough data to visualize them. +:::info +Remote Monitor is simple to set up and works well for a handful of servers. As your fleet grows, +switch to [VitoAgent](#vito-agent) for better scalability. +::: + ## Vito Agent To enable Vito to monitor your servers you need to install the VitoAgent service first on your server. diff --git a/content/docs/4.x/servers/overview.md b/content/docs/4.x/servers/overview.md new file mode 100644 index 0000000..b21a1b6 --- /dev/null +++ b/content/docs/4.x/servers/overview.md @@ -0,0 +1,59 @@ +# Server Overview + +## Introduction + +The Overview page is the landing page for a server. It gives you a quick health check at a glance: +any alerts that need attention, basic monitoring stats, recent activity, and the common server +actions. + +## Monitoring stats + +At the top of the page Vito shows summary cards for the server's core resources: + +- **CPU Load** +- **Memory Usage** +- **Disk Usage** + +Each card reflects the latest collected metric and links through to the +[Monitoring](/docs/4.x/servers/monitoring) page, where you can see the full history and more detailed +charts. + +:::info +Monitoring stats are collected by the Vito agent on the server. If the agent is not installed or is +out of date, some stats may be empty. +::: + +## Recent logs + +Below the stats, the Overview lists the server's most recent logs (provisioning steps, service +actions, and other operations Vito has run). The full history is available on the +[Logs](/docs/4.x/servers/logs) page. + +## Server actions + +The actions menu in the top right of the server pages gives you quick access to common operations: + +- **Check connection** - re-checks that Vito can reach the server over SSH and updates its status. +- **Restart** - reboots the server. +- **Check for updates** - asks the server how many OS package updates are pending. +- **Update** - installs the pending OS package updates. This is only available when updates are + available. + +## Server alerts + +Vito surfaces **server alerts** to flag conditions that need your attention. They appear at the top +of the server's pages and on the servers listing, and each includes a call to action so you can +resolve it quickly. Alerts update in real time and clear automatically once the underlying condition +is resolved. + +The following alerts can appear: + +### Restart required + +Shown when the kernel or a critical package has been updated and the server needs a reboot to +complete the upgrade. Provides a **Restart** action. + +### Package updates available + +Shown when the server has pending OS package updates. It includes the number of updates and provides +an **Update** action to install them. diff --git a/content/docs/4.x/servers/php.md b/content/docs/4.x/servers/php.md index 5c43446..31b5603 100644 --- a/content/docs/4.x/servers/php.md +++ b/content/docs/4.x/servers/php.md @@ -17,6 +17,7 @@ server creation in the `PHP` menu in the server page or in the [Services](./serv - PHP 8.2 - PHP 8.3 - PHP 8.4 +- PHP 8.5 ## Install and Uninstall diff --git a/content/docs/4.x/settings/source-controls.md b/content/docs/4.x/settings/source-controls.md index 45f9393..9f1fbc5 100644 --- a/content/docs/4.x/settings/source-controls.md +++ b/content/docs/4.x/settings/source-controls.md @@ -7,10 +7,40 @@ deployments. ## Supported Providers -- GitHub +- GitHub (personal access token) +- GitHub App - Gitlab (Cloud and Self-hosted) - Bitbucket +## GitHub App + +In v4.x you can connect GitHub through a **GitHub App** instead of a personal access token. A GitHub +App is a more secure way to connect, authenticating with short-lived, per-repository tokens rather +than a long-lived token tied to your account. + +Deployments through a GitHub App also **no longer require 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, which exists only in the environment during the deployment and is never written to disk. + +You register the app once for your Vito instance from the admin area. See +[Admin > GitHub App](/docs/4.x/admin/github-app) for the setup steps. + +Once the app is installed on a GitHub organization or account, each connected organization appears +automatically as a source control record here. These records behave differently from the other +providers: + +- They are created as **global** records (available to all projects). +- You can **edit** a record to make it non-global (scoped to a single project). +- You **cannot delete** them from within Vito. They are managed through GitHub instead. +- When you **uninstall** the app from an organization on GitHub, its record is removed from this list + automatically. + +:::info +GitHub App installations are kept in sync with GitHub via webhooks, with a periodic background sync +as a fallback. If your Vito instance is not publicly reachable, changes are picked up on the sync or +when you trigger it manually. See [Admin > GitHub App](/docs/4.x/admin/github-app#keeping-installations-in-sync). +::: + ## Required API Permissions Vito connects to the source control providers via their APIs. To connect to the source control providers the following diff --git a/content/docs/4.x/sites/application.md b/content/docs/4.x/sites/application.md index c4f5f37..258bc92 100644 --- a/content/docs/4.x/sites/application.md +++ b/content/docs/4.x/sites/application.md @@ -4,6 +4,68 @@ In the Application page you can manage your app and deployments. +## Site alerts + +Vito surfaces **site alerts** to flag conditions that need your attention. They appear at the top of +the site's pages and on the sites listing, and most include a call to action so you can resolve them +quickly. Alerts update in real time and clear automatically once the underlying condition is +resolved. While a site is still installing, alerts are suppressed. + +The following alerts can appear: + +### Installation failed + +Shown when a site's installation did not complete. The alert includes the step it failed on and the +error output, and offers a **Retry installation** action. Retrying re-runs the installation, and +steps that already completed (isolated user, vhost, cloned repository, deployed key) are detected and +skipped. + +### Pending domains + +Shown when one or more of the site's [domains](/docs/4.x/sites/domains) do not resolve to the server. +It lists the affected domains and links to **Manage Domains**, where you can fix your DNS records or +force activation. + +### SSL is disabled + +Shown when the site is not served over HTTPS even though valid certificates may exist. Provides an +**Enable SSL** action to start serving the site securely. + +### SSL expiring + +Shown when one or more of the site's SSL certificates will expire within 14 days. It lists the +affected domains and the time remaining, and links to **Manage Domains**. + +### VHost generation is disabled + +Shown when automatic vhost generation is turned off for the site, which means changes to SSL, +domains, or redirects will not update the vhost. It links to the [Settings](/docs/4.x/sites/settings) +page to review the template, and offers a **Re-enable** action. This alert is expected on sites +upgraded from an earlier version, where generation is disabled by default. + +### Site needs first deploy + +Shown for [reverse proxy sites](#reverse-proxy-sites) (such as Node and Bun) that have not yet had a +successful deployment. The application worker is created on the first successful deploy, so this +alert links to **Application** to prompt you to deploy. + +## Reverse proxy sites + +Reverse proxy site types, such as [Node](/docs/4.x/sites/site-types) and Bun, run a long-lived +process behind the webserver. For these sites the Application page shows a header card with the key +details of that process: + +- **Port** - the port your app listens on. The webserver proxies requests to this port. It must be a + non-privileged port (1024-65535), and you can change it here. +- **Start command** - the command used to launch your app (for example `node server.js`). If you do + not set one, the site type's default is used. +- **Worker** - the status of the [worker](/docs/4.x/servers/workers) that runs your app. Vito creates + this worker automatically so your start command keeps running and restarts if it stops. From the + menu you can start, stop, or restart the worker and view its logs. + +The worker status updates in real time. It begins as `pending_deploy` until the worker has been +created during the first deployment. + ## Branch You can change the branch of your cloned repository diff --git a/content/docs/4.x/sites/commands.md b/content/docs/4.x/sites/commands.md index 4cba1c1..8f1076e 100644 --- a/content/docs/4.x/sites/commands.md +++ b/content/docs/4.x/sites/commands.md @@ -2,12 +2,63 @@ ## Introduction -Commands are useful tools that allow users to run single commands on the root directory of a site. +Commands are saved, named snippets that you can run against a site on demand. They are handy for +repeatable maintenance tasks, such as clearing a cache, running a migration, or rebuilding assets, +without having to open a terminal each time. + +Each command runs in the site's root directory, as the site's +[isolated user](/docs/4.x/sites/isolation), so it has exactly the same access and environment as your +site. + +## Creating a command + +Give the command a **name** and the **command** to run. A command can be a single line or a small +multi-line script. Once saved, it appears in the site's Commands list and can be run at any time. + +## Running a command + +When you run a command, Vito executes it on the server as a background job and streams the output +back in real time. Each run is recorded, so you can review the output and status of previous +executions. ## Default Commands -Specific site types might come with default commands out of the box. For example, Laravel site comes with some of the useful artisan commands like `artisan up` or `artisan down` and etc. +Specific site types might come with default commands out of the box. For example, a Laravel site +comes with some useful artisan commands like `artisan up` and `artisan down`. + +## Environment + +Commands run with the same environment as your [deployment script](/docs/4.x/sites/application), so +the same variables are available, including: + +``` +SITE_PATH=[path to the website] +DOMAIN=[domain name] +BRANCH=[branch name] +REPOSITORY=[repository] +COMMIT_ID=[last deployed commit id] +PHP_VERSION=[the php version your site is running] +PHP_PATH=[path to the php your site is running] +``` + +The `php` alias also resolves to the site's configured PHP version, so `php` runs the correct +version automatically. + +## Installed tooling + +Commands have access to any [Site Tooling](/docs/4.x/sites/site-tooling) you have installed for the +site. Because commands run as the site's isolated user with the tooling on the `PATH`, runtimes and +package managers such as `node`, `npm`, `bun`, `yarn`, and `pnpm` can be used directly in a command, +for example: + +```sh +npm ci && npm run build +``` + +The versions used are whatever you have installed for the site through Site Tooling. ## Variables -Similar to [Scripts](../scripts.md), Commands also support variables. You can define variables with `${VARIABLE_NAME}` format and Vito will ask for an input for these variables when you run the command. +Like [Scripts](../scripts.md), commands support variables. Define a variable with the +`${VARIABLE_NAME}` format, and Vito will prompt you for its value each time you run the command. This +lets you reuse a single command with different inputs. diff --git a/content/docs/4.x/sites/create.md b/content/docs/4.x/sites/create.md index 0678bc7..5488ed2 100644 --- a/content/docs/4.x/sites/create.md +++ b/content/docs/4.x/sites/create.md @@ -31,11 +31,15 @@ You can develop a plugin to add more site types to VitoDeploy. The domain of your site. You can use a custom domain or a subdomain. Make sure to add the domain to your DNS provider and point it to your server's IP address. +After creation, you can add more domains and manage SSL per domain from the [Domains](./domains.md) page. + ### Aliases You can add aliases to your site. Aliases are additional domains that point to the same site. For example, you can add `www.example.com` as an alias for `example.com`. +Aliases are managed as alias [domains](./domains.md) once the site is created. + ### Site type fields Every site type has its own fields that you need to fill in. For example, if you select the WordPress site type, you @@ -43,8 +47,9 @@ will need to provide the WordPress admin username and password. ### User -Every site requires a unique system user. VitoDeploy creates a dedicated user on the server for each site to ensure full -isolation between sites. +Every site requires a system user. VitoDeploy creates a dedicated user on the server for each site to ensure full +isolation between sites, and in v4.x a user can be shared across several sites. -Read more about [isolation](./isolation.md). +Read more about [isolation](./isolation.md). You can also install per-site runtimes and package +managers through [Site Tooling](./site-tooling.md). diff --git a/content/docs/4.x/sites/domains.md b/content/docs/4.x/sites/domains.md new file mode 100644 index 0000000..e2ac123 --- /dev/null +++ b/content/docs/4.x/sites/domains.md @@ -0,0 +1,117 @@ +# Domains + +:::info +This page is about the domains attached to a specific **site** and their per-domain SSL. To manage a +domain's **DNS records** through a connected DNS provider, see [Domains](../domains.md). +::: + +## Introduction + +Every site in Vito is reachable through one or more **hosted domains**. The domain you enter when +creating a site becomes its **primary** domain, and you can attach additional domains to the same +site at any time, either as aliases or as redirects. + +Each domain has its own DNS resolution status and its own SSL configuration, and Vito keeps the +webserver vhost in sync as you add, change, or remove domains. + +## Domain types + +| Type | Description | +| ------------ | -------------------------------------------------------------------------------------------- | +| **Primary** | The site's main domain, set when the site is created. It cannot be deleted or deactivated. | +| **Alias** | Serves the same site content under another domain (e.g. `www.example.com` shows `example.com`). | +| **Redirect** | Sends visitors to the primary domain via an HTTP redirect (e.g. `old.example.com` to `example.com`). | + +## Adding a domain + +From the site's **Domains** page, click **Add Domain** and fill in: + +- **Domain** - the hostname to add, for example `sub.example.com`. +- **Type** - **Alias** or **Redirect** (see above). +- **SSL** - how the domain's certificate is handled (see [SSL per domain](#ssl-per-domain)). + +A domain must be unique per server. Vito will reject a domain that is already in use by another +site on the same server. + +## DNS validation + +When you add a domain, Vito checks that it actually resolves to the server before activating it. + +A domain that does not yet point at the server is held in a **pending** state and flagged on the +site, rather than being activated with a configuration that would not work. Vito automatically +re-checks pending domains **every 5 minutes for the first 24 hours**, activating them as soon as +they resolve. + +You do not have to wait for the scheduled check. From the UI you can **validate the domain on +demand**: if it now resolves to the server, the domain activates immediately and the pending warning +clears. + +### Domain status + +| Status | Meaning | +| ------------ | ------------------------------------------------------------- | +| **creating** | The domain is being set up on the server. | +| **updating** | A change to the domain is being applied. | +| **pending** | The domain does not yet resolve to the server. | +| **active** | The domain resolves and is serving traffic. | +| **inactive** | The domain has been deactivated and is not served. | +| **deleting** | The domain is being removed. | + +### Validation behind a proxy + +If your server sits behind a proxy or load balancer, a plain DNS-to-IP check is not always enough. +For these cases Vito performs an HTTP/HTTPS challenge: it writes a short-lived token and serves it +from `/.well-known/vito` on the site, then fetches that path over each address the domain resolves +to and confirms the response matches. + +:::info +The challenge is signed with your instance's `APP_KEY`, so another Vito installation cannot spoof +ownership of your domain. +::: + +## SSL per domain + +Each domain can have its own SSL method: + +| Method | Description | +| -------------------------------------- | ------------------------------------------------------------------- | +| **Disabled** | No SSL is configured for the domain. | +| **Generate Let's Encrypt Certificate** | Vito issues and manages a Let's Encrypt certificate for the domain. | +| **Custom Certificate** | Use an existing server-level certificate, including wildcards. | + +When you choose **Custom Certificate**, Vito lists only the server-level certificates that match the +domain you entered. Server-level and wildcard certificates are managed from the server's SSL +settings. + +:::info +Wildcard Let's Encrypt certificates are renewed automatically when they are within 30 days of +expiry, provided the domain is still reachable through a configured DNS provider. Let's Encrypt +certificates issued per domain also auto-renew, and Vito keeps the recorded expiry date in sync. +::: + +The available SSL methods depend on the webserver. Some webservers manage certificates differently, +so the options shown reflect what that webserver supports. + +## Activating and deactivating domains + +You can deactivate a non-primary domain to temporarily stop serving it without deleting it, and +reactivate it later. The primary domain cannot be deactivated. + +## Deleting a domain + +Non-primary domains can be deleted from the Domains page. A domain cannot be deleted while it is +still assigned to a server-level (for example, wildcard) SSL certificate. Remove the assignment +first, then delete the domain. + +## VHost generation + +Adding, changing, or removing domains regenerates the site's vhost from its template. In v4.x the +vhost is rendered with Mustache rather than Blade. + +:::warning +On sites that existed before upgrading to v4.x, vhost generation is **disabled by default** so the +upgrade does not overwrite a working configuration. You must review and enable the new template per +site before Vito will regenerate the vhost. See +[Custom VHost Configuration](/docs/4.x/prologue/breaking-changes) for details, and the site **Settings** +page to preview and enable the new template. +::: diff --git a/content/docs/4.x/sites/isolation.md b/content/docs/4.x/sites/isolation.md index c9385f5..bbc2346 100644 --- a/content/docs/4.x/sites/isolation.md +++ b/content/docs/4.x/sites/isolation.md @@ -1,16 +1,59 @@ # Site Isolation -Every site in VitoDeploy is isolated with its own system user. When you create a website, you must specify a unique -system user for that website. This ensures all sites on a server are fully isolated from each other. +Every site in VitoDeploy runs under a dedicated, non-privileged system user. Running each site as its own user +keeps sites separated from one another at the operating-system level, so a compromise of one site cannot reach another. ## How it works -When you create a new site, you need to provide a `User` field with a unique username. VitoDeploy will create a -dedicated system user on the server for that site. Each site runs under its own user, ensuring complete isolation. +When you create a site you choose an **isolated user**. VitoDeploy provisions that user on the server, and the site's +files live under the user's home directory (e.g. `/home/your-user/domain.com`). The site's PHP-FPM pool, processes, +and deployments all run as that user. -The site's files will be stored under the user's home directory (e.g., `/home/your-user/domain.com`). +## Sharing a user across sites + +In v4.x an isolated user can be **shared by multiple sites on the same server**, rather than being tied to a single +site. This is useful when several sites belong to the same project or owner and you want them to share files, runtime +versions, and tooling. + +When creating a site, the **User** field lets you either: + +- **Select an existing isolated user** on the server. Each user shows how many sites already use it. +- **Create a new user** by typing a username that does not yet exist. + +Sites that share a user also share that user's PHP-FPM pool and its installed +[tooling](/docs/4.x/sites/site-tooling) and runtime versions. + +:::info +If you prefer the older behaviour, simply give every site its own unique user. Sharing is optional. +::: + +## Usernames + +A username must: + +- Be between 3 and 32 characters long. +- Start with a lowercase letter or underscore, and end with a lowercase letter or digit. +- Contain only lowercase letters, digits, hyphens, and underscores. + +### Reserved names + +To prevent sites running as system or service accounts, VitoDeploy blocks a list of **reserved usernames**. Names such +as `root`, `www-data`, `nginx`, `mysql`, `ubuntu`, and `vito` cannot be used for an isolated user. The full list is +defined in `config/core.php` under `reserved_user_names`. + +## Deleting sites and shared users + +When you delete a site, VitoDeploy only removes the isolated user and its PHP-FPM pool if **no other site on the server +is still using them**. If the user is shared with sibling sites, the user and pool are left in place and only the +deleted site's own resources are removed. + +:::info +Operations that create, modify, or delete an isolated user run under a lock, so concurrent site actions cannot leave a +user or its FPM pool in an inconsistent state. +::: ## Why Site Isolation -Site Isolation is a security best practice. By running each site under its own system user, if one of your websites gets -hacked and the attacker gains access to that site's user, they cannot access other websites on your server. +Site Isolation is a security best practice. By running each site (or group of related sites) under its own system user, +if one site is compromised and an attacker gains access to that user, they still cannot reach sites that run under a +different user. diff --git a/content/docs/4.x/sites/redirects.md b/content/docs/4.x/sites/redirects.md index 2f37996..5730b41 100644 --- a/content/docs/4.x/sites/redirects.md +++ b/content/docs/4.x/sites/redirects.md @@ -5,6 +5,11 @@ Vito supports URL redirections for your sites. You can redirect your site to another URL or path. This is useful when you want to redirect your site to a new domain or a new path. +:::info +This page covers path-level redirects. To redirect a whole domain to your site's primary domain, add +a redirect domain on the [Domains](./domains.md) page instead. +::: + :::warning Creating or deleting site redirects will regenerate the Nginx vhost file and any manual changes to the Nginx vhost will be lost. ::: diff --git a/content/docs/4.x/sites/settings.md b/content/docs/4.x/sites/settings.md index 5534157..ee459ac 100644 --- a/content/docs/4.x/sites/settings.md +++ b/content/docs/4.x/sites/settings.md @@ -2,7 +2,14 @@ ## Introduction -In the Settings page, you can manage your website settings like its PHP version, Aliases, Custom Vhost and more. +In the Settings page you can manage your site's details, its PHP version, web directory, vhost +template, basic auth, and more. + +## Site details + +The Settings page shows read-only details for the site, including its ID, domain, type, repository, +path, status, and creation date. Several of these have inline controls to change them, described +below. ## Change PHP Version @@ -19,109 +26,65 @@ You can change the branch of your cloned repository in the Settings page. You can change the source control of your cloned repository in the Settings page. -## Update Aliases +## Web directory -You can add/remove site aliases. It will update the aliases on your site's nginx vhost configuration. +You can change the web (public) directory of your site relative to its root path, for example +`/public` for a Laravel application. Updating it regenerates the vhost. -:::info -This will only override the #[port] block in your vhost configuration. The rest will remain unchanged. -::: +## Aliases -:::info -Updating the aliases will reload the Nginx service. If you need a restart, you need to go to [services](../servers/services.md) and restart nginx manually. -::: +Site aliases are no longer managed here. In v4.x they are handled as alias +[domains](/docs/4.x/sites/domains), where you can add multiple alias and redirect domains per site, +each with its own DNS validation and SSL configuration. + +## VHost + +In v4.x the vhost is generated from a [Mustache](https://mustache.github.io) template, replacing the +custom-block model used in earlier versions. The Settings page gives you two related controls. -## Update VHost +### View VHost -It is possible to customize the virtual host configuration of your webserver (Nginx). However, it is not recommended to -do so unless you know what you are doing. +**View VHost** opens a read-only view of the vhost that is currently deployed to the server, so you +can see exactly what Vito generated. -Vito will show you the current configuration of the site, and you can modify it as you wish. +### VHost Template -Vito now uses custom blocks in the VHost configuration, to enable you to add custom configurations without your configuration being overridden by Vito. +**Edit Template** opens the Mustache template used to generate the vhost. From here you can: + +- **Edit** the template with syntax highlighting for your webserver (nginx or Caddy). +- **Preview** the generated output from your edits before saving, without touching the live config. +- **Reset** the template back to the default, which regenerates the vhost and discards your + customizations. + +Changes to the template persist across SSL, domain, and redirect updates. When a site uses a +customized template, the Settings page flags it so you know it differs from the default. :::tip -You can use the custom blocks when you write a plugin for Vito. +See the [Mustache manual](https://mustache.github.io/mustache.5.html) for the template syntax. ::: -Here is an example of Nginx vhost configuration: - -```nginx -#[header] -#[force-ssl] -#[/force-ssl] - -#[laravel-octane-map] -map $http_upgrade $connection_upgrade { - default upgrade; - '' close; -} -#[/laravel-octane-map] - -#[/header] - -server { - #[main] - #[port] - listen 80; - listen [::]:80; - #[/port] - - #[core] - server_name yourdomain.com ; - root /home/vito/yourdomain.com/public; - add_header X-Frame-Options "SAMEORIGIN"; - add_header X-Content-Type-Options "nosniff"; - charset utf-8; - access_log off; - error_log /var/log/nginx/yourdomain.com-error.log error; - location ~ /\.(?!well-known).* { - deny all; - } - #[/core] - - #[laravel-octane] - index index.php index.html; - error_page 404 /index.php; - location /index.php { - try_files /not_exists @octane; - } - location / { - try_files $uri $uri/ @octane; - } - location @octane { - set $suffix ""; - if ($uri = /index.php) { - set $suffix ?$query_string; - } - proxy_http_version 1.1; - proxy_set_header Host $http_host; - proxy_set_header Scheme $scheme; - proxy_set_header SERVER_PORT $server_port; - proxy_set_header REMOTE_ADDR $remote_addr; - proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; - proxy_set_header Upgrade $http_upgrade; - proxy_set_header Connection $connection_upgrade; - proxy_pass http://127.0.0.1:8000$suffix; - } - #[/laravel-octane] - - #[redirects] - #[/redirects] - - #[/main] -} - -#[footer] -#[/footer] -``` +### VHost generation + +Automatic vhost generation can be enabled or disabled per site. While it is disabled, changes to +SSL, domains, or redirects will not update the vhost on the server. :::warning -Most of the vhost file's blocks will get reset if you generate or modify SSLs, Aliases, or create/delete site redirects. +On sites that existed before upgrading to v4.x, vhost generation is **disabled by default** so the +upgrade does not overwrite a working configuration. Review the template, then re-enable generation +(a banner on the site provides a quick **Re-enable** action). See +[Custom VHost Configuration](/docs/4.x/prologue/breaking-changes) for details. ::: +## Basic Auth + +For sites served by nginx or Caddy, you can protect the site with HTTP Basic Authentication, adding +one or more username/password pairs. This is useful for staging and preview sites that must be +publicly reachable but not openly accessible. Basic auth is managed from the Settings page and shows +whether it is currently enabled and how many users are configured. + ## Delete You can delete the website from your server. -This will delete the files of your website and the webserver configurations related to your website from the Server. +This will delete the files of your website and the webserver configurations related to your website +from the server. diff --git a/content/docs/4.x/sites/site-tooling.md b/content/docs/4.x/sites/site-tooling.md new file mode 100644 index 0000000..684a1db --- /dev/null +++ b/content/docs/4.x/sites/site-tooling.md @@ -0,0 +1,54 @@ +# Site Tooling + +## Introduction + +Site Tooling lets you install developer runtimes and package managers, such as Node.js or Bun, for a +site without baking them into the site type. Instead of a fixed runtime version, you choose which +tools and versions a site uses, and change them whenever you need to. + +Tooling is installed for the site's [isolated user](/docs/4.x/sites/isolation) and made available on +that user's `PATH`, so the commands it provides (for example `node`, `npm`, or `bun`) can be used in +your deployment script and when working on the server. + +## Available tools + +Vito ships with the following tools out of the box: + +| Tool | Versions | Commands | +| ----------- | ------------- | -------------------- | +| **Node.js** | 24, 23, 22 | `node`, `npm`, `npx` | +| **Bun** | 1.2, 1.1, 1.0 | `bun`, `bunx` | +| **Yarn** | 4, 3, 1 | `yarn` | +| **pnpm** | 10, 9, 8 | `pnpm`, `pnpx` | + +Runtimes are installed with [Mise](https://mise.jdx.dev), which manages versions per isolated user. + +## Managing tooling + +Open the site's **Tooling** page to see every available tool with its current status. From here you +can: + +- **Install** a tool by choosing a version and clicking **Install**. +- **Change version** by selecting a different version and installing again. +- **Uninstall** a tool you no longer need. + +Installs and uninstalls run as background jobs on the server. The page updates in real time as each +operation completes, and you will be notified if one fails (check the site logs for details). + +## Required tooling + +Some site types require a particular tool to function. For example, a Node site requires the Node.js +runtime. Required tools are installed automatically and **cannot be uninstalled** while the site type +depends on them. The Tooling page marks these and explains which site type requires them. + +## Shared isolated users + +Tooling is tied to the isolated user, not the individual site. Because an isolated user can be +[shared across several sites](/docs/4.x/sites/isolation#sharing-a-user-across-sites), installing, +changing, or removing a tool affects **every site that shares that user**. + +:::warning +When a site shares its isolated user with others, the Tooling page lists the sibling sites and warns +you before you make a change. Changing or removing a tool could break those other sites if they rely +on it. +::: diff --git a/content/docs/4.x/sites/site-types.md b/content/docs/4.x/sites/site-types.md index ee8aa80..5dcb3fa 100644 --- a/content/docs/4.x/sites/site-types.md +++ b/content/docs/4.x/sites/site-types.md @@ -10,7 +10,8 @@ types for provide more features out of the box for some specific PHP application - PHP (Any other PHP applications) - Blank PHP - Laravel -- Node.js with NPM +- Node +- Bun - WordPress - PHPMyAdmin - Load Balancer @@ -36,13 +37,22 @@ Vito doesn't provide a file manager, and you need to upload your files by connec ### Laravel Laravel site type is a subtype of the PHP site type. With this separation, We will be able to provide more Laravel -specified features like Artisan commands in the future. +specified features like Artisan commands in the future. During site creation of a Laravel site, you are asked to +pick a pacakge manager, by default, Laravel uses NPM (Node), but you can select other package managers such as Bun, +pnpm or Yarn during site creation. -### Node.js with NPM +Additional tooling can always be installed via the [Site Tooling](./site-tooling.md) menu post site creation if needed. -You can deploy any Node.js application that uses NPM as a package manager with this site type including backend and frontend apps like Next.js, Nuxt.js, Express.js, etc. +### Node & Bun + +You can deploy any Node.js or Bun application with these site types including backend and frontend apps like Next.js, +Nuxt.js, Express.js, etc. [Site Tooling](./site-tooling.md) will be enabled based on the selected versions of tools selected during site +creation automatically. You are free to install other tooling as needed. + +These run as reverse proxy sites. Once deployed, you can change the port, environment variables, build +script, and start command, and manage the application worker, from the +[Application](./application#reverse-proxy-sites) page. -Deploying a Node.js app requires `build` and `start` scripts to be available in the `package.json` file. ### WordPress @@ -63,15 +73,3 @@ Vito supports PHPMyAdmin installation out of the box. It will install PHPMyAdmin You can use your server as a load balancer by adding a new site with the Load Balancer site type. Read more about [Load Balancer](./load-balancer.md). - -## Composer - -Vito handles the composer installation for you during the site creation process. - -If you want to run `composer install` after cloning the repository click the checkbox. - -If you check this, It will run the following command on the installation process after cloning the repository. - -```sh -composer install --no-interaction --prefer-dist --optimize-autoloader --no-dev -``` diff --git a/content/docs/4.x/sites/ssl.md b/content/docs/4.x/sites/ssl.md deleted file mode 100644 index ee7d07b..0000000 --- a/content/docs/4.x/sites/ssl.md +++ /dev/null @@ -1,47 +0,0 @@ -# SSL - -## Introduction - -Vito supports SSL installation for your sites. It can issue a Letsencrypt Certificate for your website, or you can -install your own Certificate. - -:::warning -Any actions related to SSLs will regenerate the Nginx vhost file and any manual changes to the Nginx vhost will be lost. -::: - -## Letsencrypt - -Let’s Encrypt is a free, automated, and open certificate authority (CA) that provides digital certificates to enable -HTTPS (SSL/TLS) for websites. It simplifies the process of securing websites by offering an automated mechanism to -issue, renew, and manage certificates without manual intervention. - -:::info -Vito uses `certbot` to issue a certificate for your domain. certbot requires an email address for the certificate and -Vito uses your user's email address for this. -::: - -## Custom SSLs - -You can also install your own Certificate. Vito will ask for your Certificate and Keys and will install them on your -server and Nginx. - -:::info -Vito encrypts the input and stores in your Vito Instance's database. -::: - -## SSL for Subdomains/Aliases - -VitoDeploy optionally allows you to install SSLs for your subdomains and aliases. You can check this option when you're -creating a new SSL. - -## Multiple SSLs - -You can add multiple SSLs to your server for a website and activate any of them at any time. - -## Force HTTPS/SSL - -If you already have an SSL installed and activated, you can click the `Force SSL` button to redirect all HTTP requests. - -:::warning -Make sure one of the SSLs is activated before enabling this option. -::: \ No newline at end of file diff --git a/lib/docs-config.ts b/lib/docs-config.ts index 77757d1..732fa82 100644 --- a/lib/docs-config.ts +++ b/lib/docs-config.ts @@ -2,7 +2,7 @@ export const VERSIONS = ["4.x", "3.x", "2.x", "1.x"] as const export const DEFAULT_VERSION = "3.x" export const VERSION_LABELS: Partial> = { - "4.x": "4.x (Beta)", + "4.x": "v4.x (Beta)", } export type Version = (typeof VERSIONS)[number] diff --git a/lib/docs.ts b/lib/docs.ts index 52fe554..9efb32c 100644 --- a/lib/docs.ts +++ b/lib/docs.ts @@ -38,6 +38,11 @@ export function getSidebar(version: Version): SidebarItem[] { label: "Prologue", items: [ { type: "doc", label: "Release Notes", id: "prologue/release-notes" }, + { + type: "doc", + label: "Breaking Changes", + id: "prologue/breaking-changes", + }, { type: "doc", label: "Upgrade Guide", id: "prologue/upgrade" }, { type: "doc", @@ -73,6 +78,7 @@ export function getSidebar(version: Version): SidebarItem[] { type: "category", label: "Servers", items: [ + { type: "doc", label: "Overview", id: "servers/overview" }, { type: "doc", label: "Create", id: "servers/create" }, { type: "doc", label: "Backups", id: "servers/backups" }, { type: "doc", label: "Database", id: "servers/database" }, @@ -96,8 +102,9 @@ export function getSidebar(version: Version): SidebarItem[] { { type: "doc", label: "Create", id: "sites/create" }, { type: "doc", label: "Site Types", id: "sites/site-types" }, { type: "doc", label: "Application", id: "sites/application" }, + { type: "doc", label: "Domains", id: "sites/domains" }, + { type: "doc", label: "Site Tooling", id: "sites/site-tooling" }, { type: "doc", label: "Commands", id: "sites/commands" }, - { type: "doc", label: "SSL", id: "sites/ssl" }, { type: "doc", label: "Settings", id: "sites/settings" }, { type: "doc", label: "Isolation", id: "sites/isolation" }, { type: "doc", label: "Load Balancer", id: "sites/load-balancer" }, @@ -177,8 +184,18 @@ export function getSidebar(version: Version): SidebarItem[] { }, ], }, + { + type: "category", + label: "Admin", + items: [ + { type: "doc", label: "Users", id: "admin/users" }, + { type: "doc", label: "Export & Import", id: "admin/export-import" }, + { type: "doc", label: "Plugins", id: "admin/plugins" }, + { type: "doc", label: "GitHub App", id: "admin/github-app" }, + { type: "doc", label: "Terminal", id: "admin/terminal" }, + ], + }, { type: "doc", label: "Diagnoses", id: "diagnoses" }, - { type: "doc", label: "Admin", id: "admin" }, ], "3.x": [ {