174 lines
5.1 KiB
Markdown
174 lines
5.1 KiB
Markdown
# 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
|
||
```
|