Skip to content

Commit a8383ea

Browse files
frjofrjo
authored
Update docs production/stand-alone to use uv etc. (#4847)
1 parent 6564f9a commit a8383ea

3 files changed

Lines changed: 69 additions & 143 deletions

File tree

‎docs/setup/deployment/development/stand-alone.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -110,7 +110,7 @@ NodeJS versions have potential to change. To allow for ease of upgrading, it is
110110
The following commands will install nvm and proceed to setup Node based off of the content of `.nvmrc`.
111111

112112
```shell
113-
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
113+
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.4/install.sh | bash
114114
```
115115

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

‎docs/setup/deployment/production/stand-alone.md‎

Lines changed: 64 additions & 138 deletions
Original file line numberDiff line numberDiff line change
@@ -6,69 +6,47 @@
66
## System Dependencies
77

88
* Git
9+
* uv
910
* Python {{ versions.python.version }}
1011
* Node {{ versions.node.version }}
1112
* PostgreSQL {{ versions.postgres.version }}
1213

13-
!!! info
14-
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.
15-
16-
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.
17-
18-
## Basic installation steps
19-
20-
<!-- NOTE! Before updating the install steps here, ensure they are reflected in the development install as well -->
21-
22-
=== "Debian"
23-
24-
This process was tested on **Ubuntu {{ versions.tested_ubuntu.version }}**. It should work on any Debian-based system.
25-
26-
Install Python pip, venv & PostgreSQL:
14+
### Get the code
2715

28-
```shell
29-
sudo apt install -y \
30-
python3-pip python3-venv \
31-
postgresql postgresql-contrib {{ versions.postgres.packages.debian }}
32-
```
16+
Use `git` to fetch the code, this will create a `hypha/` directory.
3317

34-
=== "Fedora"
18+
```shell
19+
git clone https://github.com/HyphaApp/hypha.git hypha
20+
cd hypha
21+
```
3522

36-
This process was tested on **Fedora {{ versions.tested_fedora.version }}**. It should work on RHEL as well.
23+
!!! info
24+
Everything from now on will happen inside the `hypha/` directory.
3725

38-
Install Python pip, venv & PostgreSQL:
3926

40-
```shell
41-
sudo dnf module -y reset postgresql
42-
sudo dnf module -y enable postgresql:{{ versions.postgres.version }}
43-
sudo dnf install -y \
44-
python3-pip gcc python3-devel \
45-
{{ versions.postgres.packages.fedora }} postgresql-contrib {{ versions.postgres_devel.packages.fedora }}
46-
sudo /usr/bin/postgresql-setup --initdb
47-
```
27+
### Installing uv
4828

29+
[uv](https://docs.astral.sh/uv/) is an extremely fast Python package and project manager, written in Rust. A single tool to replace pip, pip-tools, pipx, poetry, pyenv, twine, virtualenv, and more.
4930

50-
=== "macOS"
31+
```shell
32+
curl -LsSf https://astral.sh/uv/install.sh | sh
33+
```
5134

52-
This process was tested on **macOS {{ versions.tested_macos.version }}**.
35+
### Set up python virtual environment oand install python packages with uv
5336

54-
Install Python pip, venv & PostgreSQL:
37+
The uv sync command will create the virtual environment if it does not exist and install the python packages. For production we add `--frozen` so the `uv.lock` is not updated and `--no-default-frozens` so dev and docs are skipped.
5538

56-
```shell
57-
brew install {{ versions.python.packages.macos }}
58-
brew install {{ versions.postgres.packages.macos }}
59-
brew services start {{ versions.postgres.packages.macos }}
60-
```
39+
```shell
40+
uv sync --frozen --no-default-frozens
41+
```
6142

62-
----
43+
Run this command on each new deployment to update any packages.
6344

64-
### Get the code
45+
By prepending all python and pip commands with `uv` they will automatically use the virtual environment and the correct python version.
6546

66-
Use `git` to fetch the code, this will create a `hypha/` directory.
47+
!!! info
48+
While not recommended, pip can still be used to setup your Hypha environment. Just run ```python3 -m pip install -r requirements/<environment>.txt```
6749

68-
```shell
69-
git clone https://github.com/HyphaApp/hypha.git hypha
70-
cd hypha
71-
```
7250

7351
### Installing Node Version Manager
7452

@@ -77,78 +55,38 @@ NodeJS versions have potential to change. To allow for ease of upgrading, it is
7755
The following commands will install nvm and proceed to setup Node based off of the content of `.nvmrc`.
7856

7957
```shell
80-
wget -qO- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.5/install.sh | bash
58+
wget -qO- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.4/install.sh | bash
8159
export NVM_DIR="$HOME/.nvm"
8260
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh" # This loads nvm
8361
[ -s "$NVM_DIR/bash_completion" ] && \. "$NVM_DIR/bash_completion" # This loads nvm bash_completion
8462
nvm install # Install the Node version in .nvmrc
8563
nvm use # Use the Node version in .nvmrc
8664
```
8765

88-
### Python virtual environment
89-
90-
Create the virtual environment, specify the python binary to use and the directory. Then source the activate script to activate the virtual environment. The last line tells Django what settings to use.
91-
92-
```shell
93-
python3 -m venv venv/hypha
94-
source venv/hypha/bin/activate
95-
export DJANGO_SETTINGS_MODULE=hypha.settings.production
96-
```
97-
98-
Inside your activated virtual environment you will use plain `python` and `pip` commands. Everything inside the virtual environment is python 3 since we specified that when we created it.
99-
100-
### Install Python packages
101-
102-
Next, install the required packages using:
103-
104-
```shell
105-
python3 -m pip install --no-deps -r requirements.txt
106-
```
107-
108-
If utilizing application machine translations, install the required dependencies:
109-
110-
```shell
111-
python3 -m pip install -r requirements/translate.txt
112-
```
113-
or, if you are on a platform that does not support GPU processing:
114-
```shell
115-
python3 -m pip install -r requirements/translate-cpu.txt
116-
```
117-
118-
11966
### Install Node packages
12067

12168
All the needed Node packages are listed in `package.json`. Install them with this command.
12269

123-
```text
70+
```shell
12471
npm install
12572
```
12673

12774
### The Postgres database
12875

129-
Postgresql is the database used. The following commands will start the Postgresql service and login to the postgres superuser:
76+
Postgresql is the database used. See <https://docs.djangoproject.com/en/stable/ref/settings/#databases>
13077

131-
```shell
132-
sudo service postgresql start
133-
sudo su - postgres
134-
```
78+
We use `dj-database-url` so also see <https://github.com/jazzband/dj-database-url>
13579

136-
then, enter the postgresql cli with:
80+
By default Hypha looks for a database with the name "hypha". Set `APP_NAME` to change the database name.
13781

138-
```shell
139-
psql
140-
```
141-
142-
In the CLI use these commands to create the initial hypha database, and add a superuser (replacing `replace_with_username` with the user account that will be running hypha):
143-
144-
```sql
145-
CREATE DATABASE hypha;
146-
CREATE USER replace_with_username WITH SUPERUSER LOGIN;
147-
```
148-
149-
Confirm that this user has trust access in `pg\_hba.conf`. These settings can be restricted later as required.
82+
APP_NAME = env.str('APP_NAME', 'hypha')
83+
DATABASES = {
84+
'default': dj_database_url.config(
85+
conn_max_age=600,
86+
default=f'postgres:///{APP_NAME}'
87+
)
88+
}
15089

151-
To exit out of both the psql interface & the postgres user session, do `Ctrl + D` twice.
15290

15391
### Running the app
15492

@@ -160,14 +98,14 @@ Then use the following commands to test run the server:
16098

16199
```shell
162100
npm run build
163-
python manage.py collectstatic --noinput
164-
python manage.py createcachetable
165-
python manage.py migrate --noinput
166-
python manage.py sync_roles
167-
python manage.py clear_cache --cache=default
168-
python manage.py createsuperuser
169-
python manage.py wagtailsiteupdate apply.server.domain 80
170-
python manage.py runserver
101+
uv python manage.py collectstatic --noinput
102+
uv python manage.py createcachetable
103+
uv python manage.py migrate --noinput
104+
uv python manage.py sync_roles
105+
uv python manage.py clear_cache --cache=default
106+
uv python manage.py createsuperuser
107+
uv python manage.py wagtailsiteupdate apply.server.domain 80
108+
uv python manage.py runserver
171109
```
172110

173111
\(runs development server at [http://127.0.0.1:8000](http://127.0.0.1:8000)\)
@@ -224,56 +162,44 @@ Follow the instructions, and you're done.
224162

225163
### Administration
226164

227-
The Django Administration panel can be accessed via [http://apply.server.domain/django-admin/](http://sapply.erver.domain/django-admin/) \(use the email address and password you set in the `python manage.py createsuperuser` step above.\)
165+
The Django Administration panel can be accessed via `https://apply.server.domain/django-admin/` \(use the email address and password you set in the `python manage.py createsuperuser` step above.\)
228166

229-
The Apply dashboard is here: [http://apply.server.domain/dashboard/](http://apply.server.domain/dashboard/). The Wagtail admin: [http://apply.server.domain/admin](http://apply.server.domain/admin)
167+
The Apply dashboard is here: `http://apply.server.domain/dashboard/`. The Wagtail admin: `http://apply.server.domain/admin`
230168

231-
### settings
169+
### Settings
232170

233171
Here is a list of settings that can be set as environment variables or in a `hypha/settings/local.py` file.
234172

235173
**None optional:**
236174

237175
```text
238-
CACHE_CONTROL_MAX_AGE: 14400
176+
SECRET_KEY: [KEY]
239177
DJANGO_SETTINGS_MODULE: hypha.settings.production
178+
PRIMARY_HOST: www.example.org
240179
EMAIL_HOST: example.org
241180
ORG_EMAIL: hello@example.org
242181
ORG_GUIDE_URL: https://guide.example.org/
243182
ORG_LONG_NAME: Long name of your organisation
244183
ORG_SHORT_NAME: Short org name
245-
PRIMARY_HOST: www.example.org
246-
PROJECTS_AUTO_CREATE: false
247-
PROJECTS_ENABLED: true
248-
SECRET_KEY: [KEY]
249-
SEND_MESSAGES: true
250184
SERVER_EMAIL: app@example.org
185+
SEND_MESSAGES: true
251186
```
252187

253-
**Optional:**
188+
**Turn on Hypha features that are off by default:**
254189

255190
```text
256-
ANYMAIL_WEBHOOK_SECRET: [KEY]
257-
AWS_ACCESS_KEY_ID: [KEY]
258-
AWS_DEFAULT_ACL: None
259-
AWS_PRIVATE_BUCKET_NAME: private.example.org
260-
AWS_PUBLIC_BUCKET_NAME: public.example.org
261-
AWS_PUBLIC_CUSTOM_DOMAIN: public.example.org
262-
AWS_QUERYSTRING_EXPIRE: 600
263-
AWS_SECRET_ACCESS_KEY: [KEY]
264-
AWS_STORAGE_BUCKET_NAME: public.example.org
265-
BASIC_AUTH_ENABLED: true
266-
BASIC_AUTH_LOGIN: [USER]
267-
BASIC_AUTH_PASSWORD: [PASS]
268-
BASIC_AUTH_WHITELISTED_HTTP_HOSTS: example.org
269-
CLOUDFLARE_API_ZONEID: [KEY]
270-
CLOUDFLARE_BEARER_TOKEN: [KEY]
271-
MAILGUN_API_KEY: [KEY]
272-
SEND_READY_FOR_REVIEW: false
273-
SLACK_DESTINATION_ROOM: #notify
274-
SLACK_DESTINATION_ROOM_COMMENTS: #notes
275-
SLACK_DESTINATION_URL: https://slackbot-example.org/incoming/[KEY]
276-
SOCIAL_AUTH_GOOGLE_OAUTH2_KEY: [KEY]
277-
SOCIAL_AUTH_GOOGLE_OAUTH2_SECRET: [KEY]
278-
SOCIAL_AUTH_GOOGLE_OAUTH2_WHITELISTED_DOMAINS: example.org
191+
GIVE_STAFF_LEAD_PERMS: true
192+
HIDE_IDENTITY_FROM_REVIEWERS: true
193+
HIDE_STAFF_IDENTITY: true
194+
PROJECTS_AUTO_CREATE: true
195+
PROJECTS_ENABLED: true
196+
STAFF_UPLOAD_CONTRACT: true
197+
SUBMISSIONS_ARCHIVED_ACCESS_STAFF: true
198+
SUBMISSIONS_ARCHIVED_VIEW_ACCESS_STAFF: true
199+
SUBMISSIONS_DRAFT_ACCESS_STAFF: true
200+
SUBMISSIONS_DRAFT_ACCESS_STAFF_ADMIN: true
201+
TRANSITION_AFTER_ASSIGNED: true
202+
TRANSITION_AFTER_REVIEWS: true
279203
```
204+
205+
Then there are settings for S3 buckets, Slack, Mailgun, Authentication, multi languages etc. See files in `hypha/settings`.

‎mkdocs.yml‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -132,11 +132,11 @@ extra:
132132
node:
133133
version:
134134
nvm:
135-
version: 0.39.5
135+
version: 0.40.4
136136
packages:
137-
debian: https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.5/install.sh
138-
fedora: https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.5/install.sh
139-
macos: https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.5/install.sh
137+
debian: https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.4/install.sh
138+
fedora: https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.4/install.sh
139+
macos: https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.4/install.sh
140140
postgres:
141141
version: 17
142142
packages:

0 commit comments

Comments
 (0)