Skip to content

Commit 70cd7d1

Browse files
kjlippoldkjlippold
authored
Merge pull request #332 from hydroserver2/43-docker-prod
43 docker prod
2 parents c5365ad + 43baf16 commit 70cd7d1

4 files changed

Lines changed: 169 additions & 6 deletions

File tree

‎docs/.vitepress/config.ts‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -129,6 +129,10 @@ export default defineConfig({
129129
text: "Deploy to AWS",
130130
link: "/how-to/deployment/aws/manage-aws-deployment",
131131
},
132+
{
133+
text: "Deploy with Docker Compose",
134+
link: "/how-to/deployment/docker/docker-deployment-guide.md"
135+
},
132136
{
133137
text: "Setup for Local Development",
134138
link: "how-to/development/development-setup",

‎docs/how-to/deployment/aws/manage-aws-deployment.md‎

Lines changed: 10 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -68,12 +68,20 @@ The HydroServer deployment in this guide will use the following AWS services. De
6868

6969
### Configure HydroServer
7070

71+
Once HydroServer is set up and running, there are additional configuration settings you can manage through the admin dashboard.
72+
7173
1. Log in to the HydroServer admin dashboard.
7274
2. Go to **Sites** > **example.com** and update the default domain to match your HydroServer domain.
73-
3. Navigate to **Social Applications** > **Add Social Application** to register identity providers (e.g., Google, HydroShare).
75+
3. Go to **Web** to configure additional website settings.
76+
- **Instance Configuration**: Customize the HydroServer `About` page to add information about your organization.
77+
- **Analytics Configuration**: Optionally enable [Microsoft Clarity](https://clarity.microsoft.com/) for your instance.
78+
- **Map Configuration**: Customize the default map layers, view, geospatial, and elevation services.
79+
- **Map Layers**: Add additional map layer options for pages that use maps.
80+
- **Contact Information**: Add additional contact information for your organization to be displayed on the `About` page.
81+
4. Navigate to **Social Applications** > **Add Social Application** to register identity providers (e.g., Google, HydroShare).
7482
- Select a provider from the list of supported providers.
7583
- Choose a unique ID and name for the provider.
76-
- Enter the client ID/key and secret key you receieved from the provider.
84+
- Enter the client ID/key and secret key you received from the provider.
7785
- Enter optional JSON settings for the provider
7886
- **allowSignUp**: (true/false) — Controls whether this provider can be used for user sign up and login.
7987
- **allowConnection**: (true/false) — Controls whether users can connect to existing HydroServer accounts.

‎docs/how-to/deployment/docker/docker-deployment-guide.md‎

Lines changed: 143 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,143 @@
1+
# HydroServer Deployment with Docker Compose
2+
3+
This guide describes how to deploy **HydroServer** using Docker Compose.
4+
HydroServer releases are distributed as Docker images via [GitHub Container Registry (GHCR)](https://ghcr.io).
5+
6+
---
7+
8+
## Prerequisites
9+
10+
Before you begin, ensure you have the following installed:
11+
12+
- [Docker](https://docs.docker.com/get-docker/)
13+
- [Docker Compose](https://docs.docker.com/compose/install/)
14+
15+
## Docker Compose Setup
16+
17+
Below is a minimal `docker-compose.yml` example that will help you get started with a HydroServer deployment.
18+
19+
- Note: This example is intended to get you started, but is not ready to run. You should extend and modify this configuration as needed.
20+
21+
```yaml
22+
services:
23+
hydroserver-base: &hydroserver_base
24+
image: ghcr.io/hydroserver2/hydroserver-api-services:latest
25+
environment:
26+
PROXY_BASE_URL: https://hydroserver.example.com
27+
SECRET_KEY: changeme
28+
DATABASE_URL: postgres://hydroserver:changeme@database:5432/hydroserver
29+
volumes:
30+
- static:/app/static
31+
- media:/app/media
32+
33+
hydroserver-web:
34+
<<: *hydroserver_base
35+
restart: unless-stopped
36+
ports:
37+
- "8000:8000"
38+
depends_on:
39+
database:
40+
condition: service_healthy
41+
hydroserver-init:
42+
condition: service_completed_successfully
43+
command: >
44+
sh -c "gunicorn --bind 0.0.0.0:8000 --workers 3 hydroserver.wsgi:application"
45+
46+
hydroserver-init:
47+
<<: *hydroserver_base
48+
depends_on:
49+
database:
50+
condition: service_healthy
51+
command: >
52+
sh -c "python manage.py migrate &&
53+
python manage.py setup_admin_user &&
54+
python manage.py load_default_data &&
55+
python manage.py collectstatic --noinput"
56+
restart: "no"
57+
58+
database:
59+
image: postgres:17
60+
restart: unless-stopped
61+
environment:
62+
POSTGRES_DB: hydroserver
63+
POSTGRES_USER: hydroserver
64+
POSTGRES_PASSWORD: changeme
65+
volumes:
66+
- db:/var/lib/postgresql/data
67+
healthcheck:
68+
test: ["CMD-SHELL", "pg_isready -U hydroserver"]
69+
interval: 10s
70+
timeout: 5s
71+
retries: 5
72+
73+
volumes:
74+
db:
75+
static:
76+
media:
77+
```
78+
79+
For a more in-depth guide on how to use Docker Compose, visit their [documentation page](https://docs.docker.com/compose/).
80+
81+
## Environment Variables
82+
83+
There are several environment variables that can be used to configure HydroServer:
84+
- **`PROXY_BASE_URL`** – The domain name for HydroServer, including the protocol (e.g., `https://yourdomain.com`).
85+
- **`DATABASE_URL`** _(Optional)_ – The PostgreSQL database URL HydroServer will connect to.
86+
*Format:* `postgresql://{user}:{password}@{host}:{port}/{database}`
87+
- **`SMTP_URL`** – Required for email notifications (account verification, password reset).
88+
*Format:* `smtps://{user}:{password}@{host}:{port}`
89+
- **`DEBUG`** _(Optional, default: `True`)_ – Set to `True` for non-production deployments.
90+
- **`ACCOUNT_SIGNUP_ENABLED`** _(Optional, default: `False`)_ – If `False`, admins must create user accounts.
91+
- **`ACCOUNT_OWNERSHIP_ENABLED`** _(Optional, default: `False`)_ – If `False`, users cannot create new workspaces.
92+
- **`SOCIALACCOUNT_SIGNUP_ONLY`** _(Optional, default: `False`)_ – If `True`, only third-party identity providers can be used for signup.
93+
- **`ENABLE_AUDITS`** _(Optional, default: `False`)_ – If `True`, HydroServer records database audit logs.
94+
95+
## Persistent Data
96+
97+
The example compose file defines three named volumes:
98+
- **`db`** -> Stores PostgreSQL data.
99+
- **`static`** -> Stores Django static files.
100+
- **`media`** -> Stores HydroServer media files (photos).
101+
102+
In a production environment, static and media files should not be served directly by HydroServer. A separate service
103+
such as **NGINX** can be set up to route traffic to HydroServer and serve these files from `/static/` and `/media/`
104+
respectively.
105+
106+
## Configure HydroServer
107+
108+
Once HydroServer is set up and running, there are additional configuration settings you can manage through the admin dashboard.
109+
110+
1. Log in to the HydroServer admin dashboard.
111+
2. Go to **Sites** > **example.com** and update the default domain to match your HydroServer domain.
112+
3. Go to **Web** to configure additional website settings.
113+
- **Instance Configuration**: Customize the HydroServer `About` page to add information about your organization.
114+
- **Analytics Configuration**: Optionally enable [Microsoft Clarity](https://clarity.microsoft.com/) for your instance.
115+
- **Map Configuration**: Customize the default map layers, view, geospatial, and elevation services.
116+
- **Map Layers**: Add additional map layer options for pages that use maps.
117+
- **Contact Information**: Add additional contact information for your organization to be displayed on the `About` page.
118+
4. Navigate to **Social Applications** > **Add Social Application** to register identity providers (e.g., Google, HydroShare).
119+
- Select a provider from the list of supported providers.
120+
- Choose a unique ID and name for the provider.
121+
- Enter the client ID/key and secret key you received from the provider.
122+
- Enter optional JSON settings for the provider
123+
- **allowSignUp**: (true/false) — Controls whether this provider can be used for user sign up and login.
124+
- **allowConnection**: (true/false) — Controls whether users can connect to existing HydroServer accounts.
125+
- Select the default site to allow the provider to authenticate users for.
126+
5. Populate the following models with default data you want available to all users, or load the preset defaults by clicking **Load Default Data** for each model:
127+
- Roles
128+
- Observed Properties
129+
- Processing Levels
130+
- Result Qualifiers
131+
- Sensors
132+
- Units
133+
6. To configure HydroShare archival, do the following:
134+
- Configure HydroShare as an identity provider under **Social Applications**.
135+
- Add the following settings block to the HydroShare social application record:
136+
```json
137+
{
138+
"allowSignUp": false,
139+
"allowConnection": true
140+
}
141+
```
142+
- Navigate to **Orchestration Systems** > **Add Orchestration System** and create a new record with the name "HydroShare Archival Manager" and type "HydroShare".
143+
- Note: This HydroShare archival setup method is temporary and will be deprecated in a future release.

‎docs/how-to/deployment/gcp/manage-gcp-deployment.md‎

Lines changed: 12 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -75,24 +75,32 @@ The HydroServer deployment in this guide will use the following GCP services. De
7575

7676
### Configure HydroServer
7777

78+
Once HydroServer is set up and running, there are additional configuration settings you can manage through the admin dashboard.
79+
7880
1. Log in to the HydroServer admin dashboard.
7981
2. Go to **Sites** > **example.com** and update the default domain to match your HydroServer domain.
80-
3. Navigate to **Social Applications** > **Add Social Application** to register identity providers (e.g., Google, HydroShare).
82+
3. Go to **Web** to configure additional website settings.
83+
- **Instance Configuration**: Customize the HydroServer `About` page to add information about your organization.
84+
- **Analytics Configuration**: Optionally enable [Microsoft Clarity](https://clarity.microsoft.com/) for your instance.
85+
- **Map Configuration**: Customize the default map layers, view, geospatial, and elevation services.
86+
- **Map Layers**: Add additional map layer options for pages that use maps.
87+
- **Contact Information**: Add additional contact information for your organization to be displayed on the `About` page.
88+
4. Navigate to **Social Applications** > **Add Social Application** to register identity providers (e.g., Google, HydroShare).
8189
- Select a provider from the list of supported providers.
8290
- Choose a unique ID and name for the provider.
83-
- Enter the client ID/key and secret key you receieved from the provider.
91+
- Enter the client ID/key and secret key you received from the provider.
8492
- Enter optional JSON settings for the provider
8593
- **allowSignUp**: (true/false) — Controls whether this provider can be used for user sign up and login.
8694
- **allowConnection**: (true/false) — Controls whether users can connect to existing HydroServer accounts.
8795
- Select the default site to allow the provider to authenticate users for.
88-
4. Populate the following models with default data you want available to all users, or load the preset defaults by clicking **Load Default Data** for each model:
96+
5. Populate the following models with default data you want available to all users, or load the preset defaults by clicking **Load Default Data** for each model:
8997
- Roles
9098
- Observed Properties
9199
- Processing Levels
92100
- Result Qualifiers
93101
- Sensors
94102
- Units
95-
5. To configure HydroShare archival, do the following:
103+
6. To configure HydroShare archival, do the following:
96104
- Configure HydroShare as an identity provider under **Social Applications**.
97105
- Add the following settings block to the HydroShare social application record:
98106
```json

0 commit comments

Comments
 (0)