|
|
# Contributing to Hestia’s development
|
|
|
|
|
|
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 be installed on a web server. To develop Hestia on your local machine, a virtual machine is recommend.
|
|
|
|
|
|
::: warning
|
|
|
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).
|
|
|
:::
|
|
|
|
|
|
## Creating a virtual machine for development
|
|
|
|
|
|
These are example instructions for creating a virtual machine running Hestia for development.
|
|
|
|
|
|
These instructions use [Multipass](https://multipass.run/) to create the VM. Feel free to adapt the commands for any virtualization software you prefer.
|
|
|
|
|
|
::: warning
|
|
|
Sometimes the mapping between the source code directory on your local machine to the directory in the VM can be lost with a "failed to obtain exit status for remote process" error. If this happens simply unmount and remount e.g.
|
|
|
|
|
|
```bash
|
|
|
multipass unmount hestia-dev
|
|
|
multipass mount $HOME/projects/hestiacp hestia-dev:/home/ubuntu/hestiacp
|
|
|
```
|
|
|
|
|
|
:::
|
|
|
|
|
|
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 and 15G of disk space
|
|
|
|
|
|
```bash
|
|
|
multipass launch --name hestia-dev --memory 2G --disk 15G
|
|
|
```
|
|
|
|
|
|
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 hestia-dev -- sudo bash
|
|
|
sudo apt update && sudo apt install -y jq libjq1
|
|
|
```
|
|
|
|
|
|
1. Outside of the VM (in a new terminal) ensure [Node.js](https://nodejs.org/)
|
|
|
16 or later is installed
|
|
|
|
|
|
```bash
|
|
|
node --version
|
|
|
```
|
|
|
|
|
|
1. Install dependencies and build the theme files:
|
|
|
|
|
|
```bash
|
|
|
npm install
|
|
|
npm run build
|
|
|
```
|
|
|
|
|
|
1. Back in the VM terminal, 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-ubuntu.sh -D /tmp/hestiacp-src/deb/ --interactive no --email admin@example.com --password Password123 --hostname demo.hestiacp.com -f
|
|
|
```
|
|
|
|
|
|
1. Reboot the 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 and login with `admin`/`Password123`
|
|
|
|
|
|
_(proceed past any SSL errors you see when loading the page)_
|
|
|
|
|
|
```bash
|
|
|
e.g. https://192.168.64.15:8083
|
|
|
```
|
|
|
|
|
|
Hestia is now running in a virtual machine. If you'd like to make changes to the source code and test them in your browser, please continue to the next section.
|
|
|
|
|
|
## Making changes to Hestia
|
|
|
|
|
|
After setting up Hestia in a VM you can now make changes to the source code at `$HOME/projects/hestiacp` on your local machine (outside of the VM) using your editor of choice.
|
|
|
|
|
|
The following are example instructions for making a change to Hestia's UI and testing it locally.
|
|
|
|
|
|
1. At the root of the project on your local machine, ensure the latest packages are installed
|
|
|
|
|
|
```bash
|
|
|
npm 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
|
|
|
npm run 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
|
|
|
|
|
|
::: info
|
|
|
A backup is created each time the Hestia build script is run. If you run this a lot it can fill up your VM's disk space.
|
|
|
You can delete the backups by running `rm -rf /root/hst_backups` as root user on the VM.
|
|
|
:::
|
|
|
|
|
|
Please refer to the [contributing guidelines](https://github.com/hestiacp/hestiacp/blob/main/CONTRIBUTING.md) for more details on submitting code changes for review.
|
|
|
|
|
|
## Running automated tests
|
|
|
|
|
|
We currently use [Bats](https://github.com/bats-core/bats-core) to run our automated tests.
|
|
|
|
|
|
### Install
|
|
|
|
|
|
```bash
|
|
|
# Clone Hestia repo with testing submodules
|
|
|
git clone --recurse-submodules https://github.com/hestiacp/hestiacp
|
|
|
# Or, using an existing local repo with an up-to-date main branch
|
|
|
git submodule update --init --recursive
|
|
|
|
|
|
# Install Bats
|
|
|
test/test_helper/bats-core/install.sh /usr/local
|
|
|
```
|
|
|
|
|
|
### Run
|
|
|
|
|
|
::: danger
|
|
|
Do not run any testing script on a live server. It might cause issues or downtime!
|
|
|
:::
|
|
|
|
|
|
```bash
|
|
|
# Run Hestia tests
|
|
|
test/test.bats
|
|
|
```
|
