Página inicial Explorar Ajuda
Entrar
yosoyhendrix
/
hestiacp
1
0
Fork 0
Arquivos Issues 0 Pull Requests 0 Wiki
Tree: 55fe5d189b
Branches Tags
hestiacp
/
docs
/
docs
/
contributing
/
development.md

development.md 5.1 KB
Histórico Raw

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

:::

  1. Install Multipass for your OS.

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

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

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

    multipass launch --name hestia-dev --memory 2G --disk 15G

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

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

  5. SSH into the VM as root and install some required packages

    multipass exec hestia-dev -- sudo bash
sudo apt update && sudo apt install -y jq libjq1

  6. Install Node JS and Yarn via corepack enable

  7. Build the theme files with

    yarn set version stable
yarn install
yarn build

  8. Navigate to /src and build Hestia packages

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

  9. Navigate to /install and install Hestia

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

   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 VM (and exit SSH session)

    reboot

  2. Find the IP address of the VM

    multipass list

  3. 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)

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

::: info Please ensure you have Yarn v3 installed and are using Node.js v16 or higher. :::

  1. At the root of the project on your local machine, install Node dependencies

    yarn 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:

   yarn build

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

    multipass exec hestia-dev -- sudo bash
cd src

  2. Run the Hestia build script

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

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

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