From 6f1f9c8b838d8fd71b59e92936b97088375e6a76 Mon Sep 17 00:00:00 2001 From: Fredrik Jonsson Date: Wed, 8 Jan 2025 14:29:52 +0100 Subject: [PATCH] Update stand-alone dev setup docs. --- .../deployment/development/stand-alone.md | 125 +++++++++--------- 1 file changed, 60 insertions(+), 65 deletions(-) diff --git a/docs/setup/deployment/development/stand-alone.md b/docs/setup/deployment/development/stand-alone.md index a86ff37b1b..cec9ea65f5 100644 --- a/docs/setup/deployment/development/stand-alone.md +++ b/docs/setup/deployment/development/stand-alone.md @@ -8,17 +8,18 @@ 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 @@ -26,26 +27,22 @@ Make sure you have these things installed on your system: 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 ``` @@ -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. @@ -86,6 +85,23 @@ 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). @@ -93,15 +109,23 @@ NodeJS versions have potential to change. To allow for ease of upgrading, it is 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: @@ -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: @@ -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" @@ -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 @@ -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: @@ -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/