Update documentation development instructions (hestiacp#3098)

jaapmarcus · AlecRust · web-flow · commit 9d1ed0213d95 · 2022-12-04T19:54:37.000+01:00
* Update documentation development instructions

- Use yarn instead pnpm
- Update command

* Add VM and UI development instructions

* Add links to yarnpkg.com and nodejs.org

Co-authored-by: Alec Rust &lt;me@alecrust.com&gt;
diff --git a/docs/docs/contributing/development.md b/docs/docs/contributing/development.md
@@ -1,20 +1,132 @@
 # Contributing to Hestia’s development
 
-[View the current guidelines](https://github.com/hestiacp/hestiacp/blob/main/CONTRIBUTING.md).
+Hestia is an open-source project, and we welcome contributions from the community. Please read the [contributing guidelines](https://github.com/hestiacp/hestiacp/blob/main/CONTRIBUTING.md) for additional information.
+
+Hestia is designed to run on a web server. To develop Hestia locally, we recommend using a virtual machine.
 
 ::: warning
-Development builds are always unstable. If you encounter a bug please [report it via GitHub](https://github.com/hestiacp/hestiacp/issues/new/choose) or [submit a Pull request](https://github.com/hestiacp/hestiacp/pulls).
+Development builds are unstable. If you encounter a bug please [report it via GitHub](https://github.com/hestiacp/hestiacp/issues/new/choose) or [submit a Pull request](https://github.com/hestiacp/hestiacp/pulls).
+:::
+
+## Running Hestia in a virtual machine
+
+Here are example instructions for running Hestia for development in a virtual machine.
+
+These instructions use [Multipass](https://multipass.run/) to create the VM. Feel free to adapt the commands for any virtualization software you prefer.
+
+1. [Install Multipass](https://multipass.run/install) for your OS.
+
+1. [Fork Hestia](https://github.com/hestiacp/hestiacp/fork) and clone the repository to your local machine
+
+   ```bash
+   git clone https://github.com/YourUsername/hestiacp.git $HOME/projects
+   ```
+
+1. Create an Ubuntu VM with at least 2G of memory
+
+   ```bash
+   multipass launch --name hestia-dev --mem 2G
+   ```
+
+1. Map your cloned repository to the VM's home directory
+
+   ```bash
+   multipass mount $HOME/projects/hestiacp hestia-dev:/home/ubuntu/hestiacp
+   ```
+
+1. SSH into the VM as root and install some required packages
+
+   ```bash
+   multipass exec hestiacp-dev -- sudo bash
+   sudo apt update && sudo apt install -y jq libjq1
+   ```
+
+1. Navigate to `/src` and build Hestia packages
+
+   ```bash
+   cd src
+   ./hst_autocompile.sh --hestia --noinstall --keepbuild '~localsrc'
+   ```
+
+1. Navigate to `/install` and install Hestia
+
+   _(update the [installation flags](../introduction/getting-started#list-of-installation-options) to your liking, note that login credentials are set here)_
+
+   ```bash
+   cd ../install
+   bash hst-install.sh -D /tmp/hestiacp-src/deb/ --interactive no --email admin@example.com --password password123 --hostname demo.hestiacp.com -f
+   ```
+
+1. Reboot VM (and exit SSH session)
+
+   ```bash
+   reboot
+   ```
+
+1. Find the IP address of the VM
+
+   ```bash
+   multipass list
+   ```
+
+1. Visit the VM's IP address in your browser using the default Hestia port, bypass any SSL warnings and login with `admin`/`password123`
+
+   ```bash
+   e.g. https://192.168.64.15:8083
+   ```
+
+You now have Hestia running in a virtual machine. The following section will cover how to make changes to Hestia and test them locally.
+
+## Making changes to Hestia
+
+After setting up Hestia in a VM you can now make changes to the source code in `$HOME/projects/hestiacp` on your local machine using your editor of choice.
+
+The following are example instructions for making a change to Hestia's UI and testing it locally.
+
+::: info
+Please ensure you have [Yarn](https://yarnpkg.com) v3 installed and are using [Node.js](https://nodejs.org/en/) v16 or higher.
 :::
 
-## Compiling
+1. At the root of the project on your local machine, install Node dependencies
+
+   ```bash
+   yarn install
+   ```
+
+1. Make a change to a file that we can later test, then build the UI assets
+
+   _e.g. change the body background color to red in `web/css/src/base.css` then run:_
+
+   ```bash
+   yarn build
+   ```
+
+1. SSH into the VM as root and navigate to `/src`
+
+   ```bash
+   multipass exec hestia-dev -- sudo bash
+   cd src
+   ```
+
+1. Run the Hestia build script
+
+   ```bash
+   ./hst_autocompile.sh --hestia --install '~localsrc'
+   ```
+
+1. Reload the page in your browser to see your changes
+
+Please refer to the [contributing guidelines](https://github.com/hestiacp/hestiacp/blob/main/CONTRIBUTING.md) for more details on submitting code changes for review.
+
+### Building packages
 
 ::: info
 For building `hestia-nginx` or `hestia-php`, at least 2 GB of memory is required!
 :::
 
-Go into the `src` folder and run one of these commands:
+Here is more detailed information about the build scripts that are run from `src`:
 
-### Compile only
+#### Build packages only
 
 ```bash
 # Only Hestia
@@ -26,10 +138,10 @@ Go into the `src` folder and run one of these commands:
 ./hst_autocompile.sh --all --noinstall --keepbuild '~localsrc'
 ```
 
-### Compile and install
+#### Build and install packages
 
 ::: info
-Use this only if you have Hestia already installed.
+Use if you have Hestia already installed, for your changes to take effect.
 :::
 
 ```bash
@@ -42,7 +154,9 @@ Use this only if you have Hestia already installed.
 ./hst_autocompile.sh --all --install '~localsrc'
 ```
 
-## Install Hestia from packages
+## Installing Hestia from a branch
+
+The following is useful for testing a Pull Request or a branch on a fork.
 
 ```bash
 # Replace with https://github.com/username/hestiacp.git if you want to test a branch that you created yourself
@@ -64,7 +178,9 @@ bash hst-install-{os}.sh --with-debs /tmp/hestiacp-src/deb/
 
 Any option can be appended to the installer command. [See the complete list](../introduction/getting-started#list-of-installation-options).
 
-## Update Hestia from GitHub
+## Updating Hestia from GitHub
+
+The following is useful for pulling the latest staging/beta changes from GitHub and compiling the changes.
 
 ::: info
 The following method only supports building the `hestia` package. If you need to build `hestia-nginx` or `hestia-php`, use one of the previous commands.
@@ -74,7 +190,7 @@ The following method only supports building the `hestia` package. If you need to
 v-update-sys-hestia-git [USERNAME] [BRANCH]
 ```
 
-Sometimes dependencies will get added or removed when the packages are installed with `dpkg`. It is not possible to preload the dependencies. If this happens, you will see an error like:
+**Note:** Sometimes dependencies will get added or removed when the packages are installed with `dpkg`. It is not possible to preload the dependencies. If this happens, you will see an error like this:
 
 ```bash
 dpkg: error processing package hestia (–install):
@@ -87,9 +203,9 @@ To solve this issue, run:
 apt install -f
 ```
 
-## Automated testing
+## Running automated tests
 
-For automated testing, we currently use [Bats](https://github.com/bats-core/bats-core).
+For automated tests we currently use [Bats](https://github.com/bats-core/bats-core).
 
 ### Install
 
diff --git a/docs/docs/contributing/documentation.md b/docs/docs/contributing/documentation.md
@@ -4,12 +4,13 @@ The documentation is built using [VitePress](https://vitepress.vuejs.org). There
 
 ## Requirements
 
-- Node.js 16 or higher with [pnpm installed](https://pnpm.io/installation);
+- Node.js 16 or higher
+- [Yarn](https://yarnpkg.com/getting-started/install) package manager
 - A code editor with Vue and Markdown support. We suggest [Visual Studio Code](https://code.visualstudio.com).
 
 ## Viewing your changes locally
 
 1. Open the project folder in your terminal.
-2. If the dependencies are not installed yet, install them by running `pnpm i`.
-3. Run `pnpm dev`.
+2. If the dependencies are not installed yet, install them by running `yarn install`.
+3. Run `yarn docs:dev`.
 4. Navigate to `http://localhost:5173` in your browser.
