Skip to content

Stand alone

In order to get started with developing hypha locally, you'll need the following minimal setup, the setup may vary slightly for your base operating systems.

1. System dependencies

Make sure you have these things installed on your system:

Info

On Linux install them with your normal package manager. On macOS Homebrew is an excellent option. For Windows Chocolatey seems popular but we have no experience with Windows.

This project ships with .python-version and .nvmrc to support uv and nvm. You can use it to setup the correct versions of Python and Node required for this project.

Installing PostgreSQL

This process was tested on Ubuntu 22.04 LTS. It should work on any Debian-based system.

Install PostgreSQL:

sudo apt install -y postgresql postgresql-contrib postgresql-server-dev-14

This process was tested on Fedora Workstation 38. It should work on RHEL as well.

Install PostgreSQL:

sudo dnf module -y reset postgresql
sudo dnf module -y enable postgresql:14
sudo dnf install -y postgresql-server postgresql-contrib libpq-devel
sudo /usr/bin/postgresql-setup --initdb

This process was tested on macOS Sequoia 15.2.

Install PostgreSQL:

brew install postgres@14
brew services start postgres@14

2. Get the code and dependencies

Clone the repo with git

Use git to fetch the code, this will create a hypha/ directory.

git clone https://github.com/HyphaApp/hypha.git hypha
cd hypha

Now, create some local directories.

cd hypha
mkdir -p var/log media

NOTE: In production media is stored on AWS S3 but for local development you need a "media" directory. The var/log is used to store local logs, if configured.

Info

Everything from now on will happen inside the hypha/ directory.

Set up the python virtual environment and install dependencies with uv

uv sync

This vill create a .venv directory (if it does not exist) and install all python dependencies there.

All uv … commands will automatically use this virtual envionment.

If you want other commands to use it you need to run this command to activate it.

source .venv/bin/activate

Installing Node Version Manager

NodeJS versions have potential to change. To allow for ease of upgrading, it is recommended to use Node Version Manager (nvm).

The following commands will install nvm and proceed to setup Node based off of the content of .nvmrc.

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash

See Installing and Updating Node Version Manager

nvm install     # Install the Node version in .nvmrc
nvm use         # Use the Node version in .nvmrc

Install all node packages and compile JS & SCSS

Install node dependencies.

npm install

Build all JS/CSS assets for development:

npm run dev:build

Info

Hypha uses NodeJS to compile SCSS and JS from the hypha/static_src/ directory. See the package.json file for a complete list of commands.

3. Add and update Hypha configuration

Hypha supports configuration via either a local.py or a .env file:

Create an empty .env file at the root of the project:

.
├── .env
├── manage.py
├── hypha
│   ├── urls.py
│   ├── settings/
│   ├── ...
├── ...

Open .env file and add your config:

./.env
ALLOWED_HOSTS=hypha.test
BASE_URL=http://hypha.test
SECRET_KEY=<put-in-long-random-string>
DATABASE_URL=postgres://localhost/hypha

Copy the provided local.py.example file and rename it to local.py.

cp -p hypha/settings/local.py.example hypha/settings/local.py

.
├── manage.py
├── hypha
│   ├── urls.py
│   ├── settings
│   │   ├── __init__.py
│   │   ├── base.py
│   │   ├── dev.py
│   │   ├── django.py
│   │   ├── local.py
│   │   ├── local.py.example
│   │   ├── production.py
│   │   └── test.py
│   ├── ...
├── ...

Open and take a look at the local.py, it already has some sensible defaults and you can use this to override all the settings.

4. Setup the database and add initial data

Create an empty database:

createdb hypha

Ensure database name hypha is added to your hypha/settings/local.py or .env.

Let's create all the tables and schemas required by the project.

There are two ways to about it, you can either load demo data from /public/sandbox_db.dump or start with empty tables.

To load demo data run:

pg_restore --verbose --clean  --if-exists --no-acl --no-owner \
             --dbname=hypha public/sandbox_db.dump

It's not always completely up to date so run:

uv run python manage.py migrate
uv run python manage.py sync_roles

Create the cache tables.

uv run python manage.py createcachetable

Run all migrations to set up the database tables.

uv run python manage.py migrate
uv run python manage.py sync_roles

Tips

  • If createdband dropdb are not available you will need to add the Postgres bin directory to your path or call the commands with complete path.
  • If you need to delete/drop the database, you can use dropdb hypha

  • On Linux you might need to run as the "postgres" user first when setting up Postgres. Use it to create the database and set up a database user.For local development I suggest creating a user with the same name as your account, then you will not need to specify it on every command.

    su - postgres
createdb hypha
createuser [your-account-name]

5. Setup site

You will need two domain to run this app, used to serve the public and apply site on different domains

First, add these sites to the database:

$ python manage.py wagtailsiteupdate hypha.test 9001

Then, add this to your /etc/hosts file.

/etc/hosts
127.0.0.1 hypha.test

Here we are setting the public site be served at http://hypha.test:9001.

Is it safe to use .test?

The ".test" TLD is safe to use, it's reserved for testing purposes. Feel free to use another name but then remember to use it in all the commands below.

6. Create login credentials

uv run python manage.py createsuperuser

7. Run development server

You can use make serve command to run Django Development Server, watch and compile frontend changes and preview docs all at once.

make serve

Now you should be able to access the site.

Hypha development server: http://hypha.test:9001/

Documentation preview

A live preview of documentation is available at this address.

MkDocs development server: http://localhost:9100/

8. Running tests

Hypha uses ruff and py.test test runner and uses hypha/settings/testing.py for test settings. For frontend code, stylelint and biome is used.

Run the test with:

make test

For lint the code and not run the full test suite you can use:

make lint

9. Helpful URLs

Use the email address and password you set in the createsuperuser step above to login.