Contributing to Hestia’s development
Hestia is an open-source project, and we welcome contributions from the community. Please read the contributing guidelines 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.
Creating a virtual machine for development
These are example instructions for creating a virtual machine running Hestia for development.
These instructions use Multipass to create the VM. Feel free to adapt the commands for any virtualization software you prefer.
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.
multipass unmount hestia-dev multipass mount $HOME/projects/hestiacp hestia-dev:/home/ubuntu/hestiacp
Install Multipass for your OS.
Fork Hestia and clone the repository to your local machinebash
git clone https://github.com/YourUsername/hestiacp.git $HOME/projects
Create an Ubuntu VM with at least 2G of memory and 15G of disk spacebash
multipass launch --name hestia-dev --memory 2G --disk 15G
Map your cloned repository to the VM's home directorybash
multipass mount $HOME/projects/hestiacp hestia-dev:/home/ubuntu/hestiacp
SSH into the VM as root and install some required packagesbash
multipass exec hestia-dev -- sudo bash sudo apt update && sudo apt install -y jq libjq1
Outside of the VM (in a new terminal) ensure Node.js 16 or later is installedbash
Install dependencies and build the theme files:bash
npm install npm run build
Back in the VM terminal, navigate to
/srcand build Hestia packagesbash
cd src ./hst_autocompile.sh --hestia --noinstall --keepbuild '~localsrc'
/installand install Hestia
(update the installation flags 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 [email protected] --password Password123 --hostname demo.hestiacp.com -f
Reboot the VM (and exit SSH session)bash
Find the IP address of the VMbash
Visit the VM's IP address in your browser using the default Hestia port and login with
(proceed past any SSL errors you see when loading the page)bash
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.
At the root of the project on your local machine, ensure the latest packages are installedbash
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
npm run build
SSH into the VM as root and navigate to
multipass exec hestia-dev -- sudo bash cd src
Run the Hestia build scriptbash
./hst_autocompile.sh --hestia --install '~localsrc'
Reload the page in your browser to see your changes
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 for more details on submitting code changes for review.
Running automated tests
We currently use Bats to run our automated tests.
# 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
Do not run any testing script on a live server. It might cause issues or downtime!
# Run Hestia tests test/test.bats