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.

multipass unmount hestia-dev
multipass mount $HOME/projects/hestiacp hestia-dev:/home/ubuntu/hestiacp

1. Install Multipass for your OS.

2. Fork Hestia and clone the repository to your local machine

   bash

   git clone https://github.com/YourUsername/hestiacp.git $HOME/projects

3. Create an Ubuntu VM with at least 2GB of memory and 15GB of disk space

   (if running VM on ARM architecture e.g. Apple M1, use at least 12GB of memory)

   bash

   multipass launch --name hestia-dev --memory 4G --disk 15G --cpus 4

4. Map your cloned repository to the VM's home directory

   bash

   multipass mount $HOME/projects/hestiacp hestia-dev:/home/ubuntu/hestiacp

5. 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

6. Outside of the VM (in a new terminal) ensure Node.js 16 or later is installed

   bash

   node --version

7. Install dependencies and build the theme files

   bash

   npm install
   npm run build

8. Back in the VM terminal, navigate to /src and build Hestia packages

   bash

   cd src
   ./hst_autocompile.sh --all --noinstall --keepbuild '~localsrc'

9. Navigate to /install and install Hestia with these flags

   (update the installation flags to your liking, note that login credentials are set here)

   bash

   cd ../install
   bash hst-install-ubuntu.sh --hostname demo.hestiacp.com --email [email protected] --username admin --password Password123 --with-debs /tmp/hestiacp-src/deb/ --interactive no --force

10. Reboot the VM (and exit SSH session)

    bash

    reboot

11. Find the IP address of the VM

    bash

    multipass list

12. 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

2. 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

3. SSH into the VM as root and navigate to /src

   bash

   multipass exec hestia-dev -- sudo bash
   cd src

4. Run the Hestia build script

   bash

   ./hst_autocompile.sh --hestia --install '~localsrc'

5. Reload the page in your browser to see your changes

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.

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 ​

# Run Hestia tests
test/test.bats