Skip to content

Commit

Permalink
Update stand-alone dev setup docs.
Browse files Browse the repository at this point in the history
  • Loading branch information
@frjo
frjo committed Jan 8, 2025
1 parent 9185a07 commit 6f1f9c8
Showing 1 changed file with 60 additions and 65 deletions.
125 changes: 60 additions & 65 deletions docs/setup/deployment/development/stand-alone.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -8,44 +8,41 @@ minimal setup, the setup may vary slightly for your base operating systems.
Make sure you have these things installed on your system:

* Git – [Installation Guide](https://git-scm.com/downloads)
* Python {{ versions.python.version }}
* uv – [Installation Guide](https://docs.astral.sh/uv/#getting-started)
* Python {{ versions.python.version }} (installed automatically with uv)
* Node {{ versions.node.version }}
* PostgreSQL {{ versions.postgres.version }} (with `libpq-dev` on Linux)

!!! info
On Linux install them with your normal package manager. On macOS [Homebrew] is an excellent option. For Windows [Chocolatey](https://chocolatey.org/) seems popular but we have no experience with Windows.
On Linux install them with your normal package manager. On macOS [Homebrew](https://brew.sh/) is an excellent option. For Windows [Chocolatey](https://chocolatey.org/) seems popular but we have no experience with Windows.

This project ships with `.python-version` and `.nvmrc` to support **[pyenv]** and **[nvm]**. You can use it to setup the correct versions of Python and Node required for this project.
This project ships with `.python-version` and `.nvmrc` to support **[uv](https://docs.astral.sh/uv/)** and **[nvm](https://github.com/nvm-sh/nvm#readme)**. You can use it to setup the correct versions of Python and Node required for this project.


### Basic installation steps
### Installing PostgreSQL

<!-- NOTE! Before updating the install steps here, ensure they are reflected in the production install as well -->

=== "Debian"

This process was tested on **Ubuntu {{ versions.tested_ubuntu.version }}**. It should work on any Debian-based system.

Install Python pip, venv & PostgreSQL:
Install PostgreSQL:

```shell
sudo apt install -y \
python3-pip python3-venv \
postgresql postgresql-contrib {{ versions.postgres.packages.debian }}
sudo apt install -y postgresql postgresql-contrib {{ versions.postgres.packages.debian }}
```

=== "Fedora"

This process was tested on **Fedora {{ versions.tested_fedora.version }}**. It should work on RHEL as well.

Install Python pip, venv & PostgreSQL:
Install PostgreSQL:

```shell
sudo dnf module -y reset postgresql
sudo dnf module -y enable postgresql:{{ versions.postgres.version }}
sudo dnf install -y \
python3-pip gcc python3-devel \
{{ versions.postgres.packages.fedora }} postgresql-contrib {{ versions.postgres_devel.packages.fedora }}
sudo dnf install -y {{ versions.postgres.packages.fedora }} postgresql-contrib {{ versions.postgres_devel.packages.fedora }}
sudo /usr/bin/postgresql-setup --initdb
```

Expand All @@ -54,17 +51,19 @@ Make sure you have these things installed on your system:

This process was tested on **macOS {{ versions.tested_macos.version }}**.

Install Python pip, venv & PostgreSQL:
Install PostgreSQL:

```shell
brew install {{ versions.python.packages.macos }}
brew install {{ versions.postgres.packages.macos }}
brew services start {{ versions.postgres.packages.macos }}
```

----

## Get the code

## Get the code and dependencies

### Clone the repo with git

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

Expand All @@ -86,22 +85,47 @@ NOTE: In production media is stored on AWS S3 but for local development you need
Everything from now on will happen inside the `hypha/` directory.


### Set up the python virtual environment and install dependencies with uv

```shell
uv venv
uv sync
```

This vill create a `.venv` directory 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.

```shell
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)](https://github.com/nvm-sh/nvm).

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

```shell
wget -qO- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.5/install.sh | bash
export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh" # This loads nvm
[ -s "$NVM_DIR/bash_completion" ] && \. "$NVM_DIR/bash_completion" # This loads nvm bash_completion
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
```

See [Installing and Updating Node Version Manager](https://github.com/nvm-sh/nvm?tab=readme-ov-file#installing-and-updating)

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

## Compile JS & SCSS
### Install all node packages and compile JS & SCSS

Install node dependencies.

```shell
npm install
```

Build all JS/CSS assets for development:

Expand All @@ -114,7 +138,7 @@ npm run dev:build
file for a complete list of commands.


## Add/Update Configuration
## Add and Update Hypha configuration

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

Expand Down Expand Up @@ -195,22 +219,22 @@ There are two ways to about it, you can either load demo data from `/public/san
It's not always completely up to date so run:

```shell
python3 manage.py migrate
python3 manage.py sync_roles
uv run python manage.py migrate
uv run python manage.py sync_roles
```

=== "From Scratch"
Create the cache tables.

```text
python3 manage.py createcachetable
uv run python manage.py createcachetable
```

Run all migrations to set up the database tables.

```text
python3 manage.py migrate
python3 manage.py sync_roles
uv run python manage.py migrate
uv run python manage.py sync_roles
```

!!! tip "Tips"
Expand All @@ -225,7 +249,7 @@ There are two ways to about it, you can either load demo data from `/public/san
createuser [your-account-name]
```

## Setup Sites
## Setup site

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

Expand All @@ -250,56 +274,31 @@ Here we are setting the public site be served at http://hypha.test:9001.
## Create Login credentials

```shell
python3 manage.py createsuperuser
uv run python manage.py createsuperuser
```

## Run Development Server

```shell
python3 manage.py runserver 0.0.0.0:9001 --settings=hypha.settings.dev
```

Alternatively, you can also use `make serve-django`


Now you should be able to access the site:

2. Apply Site: [http://hypha.test:9001/](http://hypha.test:9001/)


## Documentation

To live preview of documentation, while you writing it.

Activate your virtual environment and install dependencies:
You can use `make serve` command to run Django Development Server, watch and compile frontend changes and preview docs all at once.

```shell
source venv/bin/activate
python3 -m pip install --no-deps -r requirements/dev.txt
make serve
```

If utilizing application machine translations, install the required dependencies:
Now you should be able to access the site.

```shell
python3 -m pip install -r requirements/translate.txt
```
Hypha development server: [http://hypha.test:9001/](http://hypha.test:9001/)

Run:
```shell
make serve-docs
```

Open http://localhost:9100/ to preview the documentation site.
### Documentation preview

A live preview of documentation is available at this address.

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

MkDocs development server: [http://localhost:9100/](http://localhost:9100/)

## Running tests

Hypha uses `ruff` and [py.test](https://pytest-django.readthedocs.io/en/latest/) test runner and uses `hypha/settings/testing.py` for test settings.
For frontend code, stylelint and eslint is used.
For frontend code, stylelint and biome is used.

Run the test with:

Expand All @@ -320,7 +319,3 @@ make lint
* The Django Administration panel: [http://hypha.test:9001/django-admin/](http://hypha.test:9001/django-admin/)

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

[nvm]: https://github.com/nvm-sh/nvm#readme
[pyenv]: https://github.com/pyenv/pyenv#readme
[Homebrew]: https://brew.sh/

0 comments on commit 6f1f9c8

Please sign in to comment.