Without Docker¶
In order to have get started with developing hypha locally, you'll need these minimal setup, the setup may vary slightly for your base operating systems.
System Dependencies¶
Make sure you have these things installed on your system:
- Git
- Python 3.10.x
- PostgreSQL 12.x (with
libpq-dev
on Linux) - Node 16.x
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.
Get Source Code¶
Use git
to fetch the code, this will create a hypha/
directory.
Now, create some local directories.
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.
OBS! Everything from now on will happen inside the hypha/
directory.
Install project dependencies¶
First create and activate python virtual environment:
Now, install Python packages inside the virtual environment:
Add/Update Configuration¶
There are two ways to manage the Django settings in Hypha:
Using hypha/settings/local.py
When you use the "dev" settings it will included all the setting you put in local.py
. Copy the local settings example file.
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.
Using .env
file
It is also possible to use a local .env
, to use it create a new .env
file at the root of the project.
ALLOWED_HOSTS=apply.hypha.test,hypha.test
BASE_URL=http://hypha.test
SECRET_KEY=<put-in-long-random-string>
DATABASE_URL=postgres://localhost/hypha-db
Info
On production it's recommended to use environment variables for all settings. For local development putting them in a file is however convenient.
Setup Database and Initial Data¶
Create an empty database:
Ensure database name hypha-db
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.
Tips
- If
createdb
anddropdb
are not available you will need to add the Postgres bin directory to yourpath
or call the commands with complete path. - If you need to delete/drop the database, you can use
$ dropdb hypha-db
-
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.
Setup Sites¶
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:
Then, add this to your /etc/hosts
file.
Here we are setting the public site be served at http://hypha.test:9001 and apply site to http://apply.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.
Create Login credentials¶
Frontend Setup¶
Hypha uses nodejs to compile SCSS and JS from the static_src
directory. If are not required to touch them, you can skip these step.
Install node dependencies:
Build all assets for development:
Tip
See the package.json
file for a complete list of commands. Here are the most common in development.
Run Development Server¶
Alternatively, you can also use $ make serve-django
Now you should be able to access the sites:
- Public Site: http://hypha.test:9001/
- Apply Site: http://apply.hypha.test:9001/
Documentation¶
To live preview of documentation, while you writing it.
Activate your virtual environment and install dependencies:
Run:
Open http://localhost:9100/ to preview the documentation site.
Tip
You can use $ make serve
command to run Django Development Server, watch and compile frontend changes and preview docs all at once.
Running tests¶
Hypha uses ruff
and py.test test runner and uses hypha/settings/testing.py
for test settings.
For frontend code, stylelint and eslint is used.
Run the test with:
For lint the code and not run the full test suite you can use:
Helpful URLs¶
- The Apply dashboard: http://apply.hypha.test:9001/dashboard/
- The Apply Wagtail admin: http://apply.hypha.test:9001/admin/
- The Django Administration panel: http://apply.hypha.test:9001/django-admin/
Use the email address and password you set in the createsuperuser
step above to login.