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.
WARNING
Development builds are unstable. If you encounter a bug please report it via GitHub or submit a Pull Request.
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.
WARNING
Sometimes the mapping between the source code directory on your local machine to the directory in the VM can be lost. 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 machine
bashgit clone https://github.com/YourUsername/hestiacp.git $HOME/projects
Create an Ubuntu VM with at least 2G of memory and 15G of disk space
bashmultipass launch --name hestia-dev --memory 2G --disk 15G
Map your cloned repository to the VM's home directory
bashmultipass mount $HOME/projects/hestiacp hestia-dev:/home/ubuntu/hestiacp
SSH into the VM as root and install some required packages
bashmultipass exec hestia-dev -- sudo bash sudo apt update && sudo apt install -y jq libjq1
Install Node JS and Yarn
npm install --global yarn
Build the theme files with
bashyarn set version stable yarn install yarn build
Navigate to
/src
and build Hestia packagesbashcd src ./hst_autocompile.sh --hestia --noinstall --keepbuild '~localsrc'
Navigate to
/install
and install Hestia(update the installation flags to your liking, note that login credentials are set here)
bashcd ../install bash hst-install-ubuntu.sh -D /tmp/hestiacp-src/deb/ --interactive no --email [email protected] --password Password123 --hostname demo.hestiacp.com -f
Reboot VM (and exit SSH session)
bashreboot
Find the IP address of the VM
bashmultipass list
Visit the VM's IP address in your browser using the default Hestia port and login with
admin
/Password123
(bypass any SSL errors you see when loading the page)
bashe.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, 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 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.
At the root of the project on your local machine, install Node dependencies
bashyarn install
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:bashyarn build
SSH into the VM as root and navigate to
/src
bashmultipass exec hestia-dev -- sudo bash cd src
Run the Hestia build script
bash./hst_autocompile.sh --hestia --install '~localsrc'
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 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!
Here is more detailed information about the build scripts that are run from src
:
Build packages only
# Only Hestia
./hst_autocompile.sh --hestia --noinstall --keepbuild '~localsrc'
# Hestia + hestia-nginx and hestia-php
./hst_autocompile.sh --all --noinstall --keepbuild '~localsrc'
Build and install packages
INFO
Use if you have Hestia already installed, for your changes to take effect.
# Only Hestia
./hst_autocompile.sh --hestia --install '~localsrc'
# Hestia + hestia-nginx and hestia-php
./hst_autocompile.sh --all --install '~localsrc'
Installing Hestia from a branch
The following is useful for testing a Pull Request or a branch on a fork.
Make sure to install Node JS and Yarn npm install --global yarn
before.
# Replace with https://github.com/username/hestiacp.git if you want to test a branch that you created yourself
git clone https://github.com/hestiacp/hestiacp.git
cd ./hestiacp/
# Replace main with the branch you want to test
git checkout main
# Enable Yarn 3.x
yarn set version stable
# Install Dependencies
yarn install
# Build
yarn build
cd ./src/
# Compile packages
./hst_autocompile.sh --all --noinstall --keepbuild '~localsrc'
cd ../install
bash hst-install-{os}.sh --with-debs /tmp/hestiacp-src/deb/
Any option can be appended to the installer command. See the complete list.
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.
v-update-sys-hestia-git [USERNAME] [BRANCH]
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:
dpkg: error processing package hestia (–install):
dependency problems - leaving unconfigured
To solve this issue, run:
apt install -f
Running automated tests
For automated tests we currently use Bats.
Install
# 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!
# Run Hestia tests
test/test.bats