From 2760efe1243b7e33d33400e93e614553acd4933e 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. --- .../contribute-to-documentation.md | 4 +- .../contributing/developer-tips.md | 80 ++++++++-- docs/setup/administrators/cron-jobs.md | 8 +- .../deployment/development/stand-alone.md | 141 +++++++++--------- .../deployment/production/stand-alone.md | 2 +- 5 files changed, 143 insertions(+), 92 deletions(-) diff --git a/docs/getting-started/contributing/contribute-to-documentation.md b/docs/getting-started/contributing/contribute-to-documentation.md index f1f80f1109..ad629691bc 100644 --- a/docs/getting-started/contributing/contribute-to-documentation.md +++ b/docs/getting-started/contributing/contribute-to-documentation.md @@ -1,4 +1,4 @@ -# Contribute to Documentation +# Contribute to documentation Most of the work on the Hypha User Guide takes place on the [project’s GitHub repository](https://github.com/HyphaApp/hypha/). To get started, check out the list of [open issues](https://github.com/HyphaApp/hypha/issues) and pull requests. By contributing to the Hypha User Guide, you’re expected to follow the [Code of Conduct](./code-of-conduct.md). @@ -19,7 +19,7 @@ This project consists of several distinct documentation types with specific purp Provides step-by-step instructions on how to set up a local instance of Hypha. > Write technical documentation with a new developer in mind. Create a quickstart doc wherever possible. What is the bare minimum information that a user needs to get started with the feature that you are documenting? Start there. -### User Guides +### User guides Guides are focused on accomplishing a specific task and can assume some level of prerequisite knowledge. There may be multiple approaches to accomplishing a task, and we welcome your input. diff --git a/docs/getting-started/contributing/developer-tips.md b/docs/getting-started/contributing/developer-tips.md index 7fcd666836..b0efbb683b 100644 --- a/docs/getting-started/contributing/developer-tips.md +++ b/docs/getting-started/contributing/developer-tips.md @@ -1,4 +1,4 @@ -# Hypha developer tips +# Developer tips ## Git configuration and commands @@ -24,11 +24,71 @@ To update the feature branch on GitHub you then need to do a forced push. Instea git push --force-with-lease ``` +## Coding style and linting in pre-commit hook + +Hypha's coding style is enforced by ruff, stylelint and biome. + +Install pre-commit to auto-format the code before each commit: + +```shell +pre-commit install +``` + +If you want to check all files without committing you can run: + +```shell +pre-commit run --all-files +``` + +The pre-commit hook also updates the requirements files for you, see next section about uv. + + +## Make best use of uv + +For development [uv](https://docs.astral.sh/uv/) is a Hypha requirement. It is fast and easy to use. + +uv is used to: + +* Setup the virtual environment +* Install python dependencies. +* Add and remove python packages. +* Update python packages. +* Generate the requirements files. + +See also [Stand alone development setup](/setup/deployment/development/stand-alone/) + +### Add and remove packages with uv + +All python requirements are listed in `pyproject.toml`. + +To add a package: + +```shell +uv add django-htmx +``` + +To remove a package: + +```shell +uv remove django-select2 +``` + +After adding or removing a packages run this to update `uv.lock`. + +```shell +uv sync +``` + +When you attempt to commit the pre-commit hook will update the requirements files for you. + +The requirements files exist so you do not need uv for deployment. + + ## Postgres snapshots/restore Hypha dev requirements contain the [dslr](https://github.com/mixxorz/DSLR) tool. Use this for fast snapshots and restores of the postgres database. -Perfekt when testing migrations and other times when you need to reset the database or switch between databases. +Perfect when testing migrations and other times when you need to reset the database or switch between databases. Take a snapshot, you can have as many as you like. @@ -56,23 +116,21 @@ dslr list ## Commands in Makefile -This is the one stop place to find commands for runiing test, build resources and docs, linting and code style checks/fixes. - -## Coding style and linting in pre-commit hook - -Hypha's coding style is enforced by ruff and prettier and comes pre-configured with prettier. +This is the one stop place to find commands for running test, build resources and docs, linting and code style checks/fixes. -Install pre-commit to auto-format the code before each commit: +The one command you will be running the most is: ```shell -pre-commit install +make serve ``` +This command runs `npm watch` to keep the front end updates and runs development servers for both Hypha app and the Hypha docs. + ## Editor extensions -If you editor does not a Language Server Protocol (LSP) preinstalled make sure to add the plugin for it. Then add "LSP-ruff" for a fast Python linter and code transformation tool. +If you editor does not have a Language Server Protocol (LSP) preinstalled make sure to add the plugin for it. Then add "LSP-ruff" for a fast Python linter and code transformation tool. -Your editor most likely have plugins for the other languages Hypha uses as well, css/scss, yaml and html. We recoment to install them as well. +Your editor most likely have plugins for the other languages Hypha uses as well, css/scss, yaml and html. We recommend to install them as well. ## Shell configuration diff --git a/docs/setup/administrators/cron-jobs.md b/docs/setup/administrators/cron-jobs.md index e4a2ff9fef..8d3e496493 100644 --- a/docs/setup/administrators/cron-jobs.md +++ b/docs/setup/administrators/cron-jobs.md @@ -1,8 +1,8 @@ -# Possible Cron Commands +# Possible cron commands Hypha comes stock with management commands that can be utilized in tandem with a job scheduler to automate specific tasks -## Account Cleanup +## Account cleanup Accounts that haven't been logged into in 5 months can be marked as inactive with the following command: @@ -10,7 +10,7 @@ Accounts that haven't been logged into in 5 months can be marked as inactive wit python3 manage.py accounts_cleanup ``` -## Drafts Cleanup +## Drafts cleanup Drafts that haven't been modified in a specified time (in days) can be deleted with the following command: @@ -26,4 +26,4 @@ Example: to delete all drafts that haven't been modified in a year without a con ```shell python3 manage.py drafts_cleanup 365 --noinput -``` \ No newline at end of file +``` diff --git a/docs/setup/deployment/development/stand-alone.md b/docs/setup/deployment/development/stand-alone.md index a86ff37b1b..4d26b1b3f7 100644 --- a/docs/setup/deployment/development/stand-alone.md +++ b/docs/setup/deployment/development/stand-alone.md @@ -1,24 +1,24 @@ -# Stand Alone +# Stand alone -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. +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. -## System Dependencies +## 1. System dependencies 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 +26,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 +50,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 + +## 2. Get the code and dependencies + +### Clone the repo with git Use `git` to fetch the code, this will create a `hypha/` directory. @@ -86,6 +84,22 @@ 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 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. + +```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 +107,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 +136,7 @@ npm run dev:build file for a complete list of commands. -## Add/Update Configuration +## 3. Add and update Hypha configuration Hypha supports configuration via either a `local.py` or a `.env` file: @@ -170,7 +192,7 @@ Hypha supports configuration via either a `local.py` or a `.env` 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. -## Setup Database and Initial Data +## 4. Setup the database and add initial data Create an empty database: @@ -195,22 +217,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 +247,7 @@ There are two ways to about it, you can either load demo data from `/public/san createuser [your-account-name] ``` -## Setup Sites +## 5. Setup site You will need two domain to run this app, used to serve the public and apply site on different domains @@ -247,59 +269,34 @@ Here we are setting the public site be served at http://hypha.test:9001. The "[.test](https://en.wikipedia.org/wiki/.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 - -```shell -python3 manage.py createsuperuser -``` - -## Run Development Server +## 6. Create login credentials ```shell -python3 manage.py runserver 0.0.0.0:9001 --settings=hypha.settings.dev +uv run python manage.py createsuperuser ``` -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/) - +## 7. Run development server -## 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 +## 8. 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: @@ -313,14 +310,10 @@ For lint the code and not run the full test suite you can use: make lint ``` -## Helpful URLs +## 9. Helpful URLs * The Apply dashboard: [http://hypha.test:9001/dashboard/](http://hypha.test:9001/dashboard/) * The Apply Wagtail admin: [http://hypha.test:9001/admin/](http://hypha.test:9001/admin/) * 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/ diff --git a/docs/setup/deployment/production/stand-alone.md b/docs/setup/deployment/production/stand-alone.md index 844b2f4680..bf995dabc3 100644 --- a/docs/setup/deployment/production/stand-alone.md +++ b/docs/setup/deployment/production/stand-alone.md @@ -1,4 +1,4 @@ -# Stand Alone +# Stand alone ## Standalone Server/VPS