Skip to content

Commit 741306f

Browse files
gilzowchadwcarlsonchadcarlsonAnouckColson
authored
[Django + Flask] Getting Started Frameworks section for Upsun (#3816)
* WIP: initial changes to the Django stacks page * finishes out the remaining steps, small configuration change * adds flask instructions * corrects indentation between from and to for deploy hook examples * Update sites/friday/src/get-started/stacks/django.md Co-authored-by: Chad Carlson <[email protected]> * Update sites/friday/src/get-started/stacks/django.md Co-authored-by: Chad Carlson <[email protected]> * Update sites/friday/src/get-started/stacks/flask.md Co-authored-by: Chad Carlson <[email protected]> * adds the remaining bits to the flask doc * adds section on alternative web servers and db migrate * removes naming a specific number of remaining steps * Match Django guide with the WordPress guide. * Match Flask guide with the WordPress format. * Doc review --------- Co-authored-by: Chad Carlson <[email protected]> Co-authored-by: chadcarlson <[email protected]> Co-authored-by: Anouck Colson <[email protected]>
1 parent d689343 commit 741306f

File tree

3 files changed

+559
-30
lines changed

3 files changed

+559
-30
lines changed

‎sites/upsun/config/_default/params.yaml

+1-1
Original file line numberDiff line numberDiff line change
@@ -48,7 +48,7 @@ vendor:
4848
console: https://console.upsun.com/
4949
api: https://proxy.upsun.com/
5050
host: upsun.com
51-
hostname: upsunapp.com
51+
hostname: platformsh.site
5252
register: https://auth.upsun.com/register
5353

5454
# Images (kept in static/)

‎sites/upsun/src/get-started/stacks/django.md

+195-14
Original file line numberDiff line numberDiff line change
@@ -1,41 +1,222 @@
11
---
2-
title: Deploying Django on Upsun
2+
title: Deploying Django on {{% vendor/name %}}
33
sidebarTitle: Django
44
sectionBefore: Python
55
layout: single
66
weight: -80
77
description: |
8-
Welcome to the Upsun documentation specific to the Django framework on Upsun.
9-
It includes common reference materials useful for deploying Django, but also external community and blog resources that cover more advanced topics relevant for the framework.
8+
Complete the last required steps to successfully deploy Django on {{% vendor/name %}}.
109
---
1110

12-
{{< note title="Hello, there!" theme="info" >}}
11+
{{< note title="Note" theme="info" >}}
1312

14-
{{% description %}}
13+
Before you start, check out the [{{% vendor/name %}} demo app](https://console.upsun.com/projects/create-project) and the main [Getting started guide](/get-started/here/_index.md).
14+
They provide all of the core concepts and common commands you need to know before using the materials below.
1515

16-
Before you proceed, be sure to checkout the [{{% vendor/name %}} demo app](https://console.upsun.com/projects/create-project) and the main [Getting started guide](/get-started/here/_index.md). These two resources provide all of the core concepts and common commands you'll need to know before using the materials below.
16+
{{< /note >}}
17+
18+
For Django to successfully deploy and operate, after completing the [Getting started guide](/get-started/here/_index.md),
19+
you still need to make a few changes to your {{% vendor/name %}} configuration.
20+
21+
## 1. Leverage environment variables
22+
23+
Your `settings.py` file may allow for environment variables to be set for common pieces of configuration.
24+
In this case, add and commit a `.environment` file that includes those details.
25+
26+
```bash {location=".environment"}
27+
export DJANGO_SETTINGS_MODULE=config.settings.production
28+
export DJANGO_SECRET_KEY="$PLATFORM_PROJECT_ENTROPY"
29+
export DJANGO_ALLOWED_HOSTS=".{{< vendor/urlraw "hostname" >}}"
30+
```
31+
32+
{{< note theme="warning" title="Warning" >}}
33+
34+
Not all Django apps allow for configuration in this way.
35+
See the following sections to see how other common settings should be set on {{% vendor/name %}}.
1736

1837
{{< /note >}}
1938

20-
## Getting started
39+
## 2. Configure `ALLOWED_HOSTS`
40+
41+
Your `settings.py` file may not allow you to use an environment variable like `DJANGO_ALLOWED_HOSTS`.
42+
If so, to configure allowed hosts, update your `settings.py` file to include `{{< vendor/urlraw "hostname" >}}`:
43+
44+
```py {location="settings.py"}
45+
ALLOWED_HOSTS = [
46+
'localhost',
47+
'127.0.0.1',
48+
'.{{< vendor/urlraw "hostname" >}}',
49+
]
50+
```
51+
52+
Appending `.{{< vendor/urlraw "hostname" >}}` to `ALLOWED_HOSTS` allows for all URLs generated for {{% vendor/name %}} preview environments.
53+
54+
## 3. {{% vendor/name %}}-specific settings
55+
56+
Near the bottom of your `settings.py` file, define a block that:
57+
58+
- Detects when Django is running on an {{% vendor/name %}} environment
59+
- Override previous settings
60+
61+
If your configuration is split into a `production.py` file for production settings, place it there instead.
62+
63+
```py {location="settings.py"}
64+
# Production/{{% vendor/name %}} settings.
65+
if (os.getenv('PLATFORM_APPLICATION_NAME') is not None):
66+
DEBUG = False
67+
68+
# Static dir.
69+
if (os.getenv('PLATFORM_APP_DIR') is not None):
70+
STATIC_ROOT = os.path.join(os.getenv('PLATFORM_APP_DIR'), 'static')
71+
72+
# Secret Key.
73+
if (os.getenv('PLATFORM_PROJECT_ENTROPY') is not None):
74+
SECRET_KEY = os.getenv('PLATFORM_PROJECT_ENTROPY')
75+
76+
# Production database configuration.
77+
if (os.getenv('PLATFORM_ENVIRONMENT') is not None):
78+
DATABASES = {
79+
'default': {
80+
'ENGINE': 'django.db.backends.postgresql',
81+
'NAME': os.getenv('DATABASE_PATH'),
82+
'USER': os.getenv('DATABASE_USERNAME'),
83+
'PASSWORD': os.getenv('DATABASE_PASSWORD'),
84+
'HOST': os.getenv('DATABASE_HOST'),
85+
'PORT': os.getenv('DATABASE_PORT'),
86+
},
87+
'sqlite': {
88+
'ENGINE': 'django.db.backends.sqlite3',
89+
'NAME': os.path.join(BASE_DIR, 'db.sqlite3'),
90+
}
91+
}
92+
```
93+
94+
This update includes a few important changes:
95+
96+
1. **Overwrites.** If the `PLATFORM_APPLICATION_NAME` {{% vendor/name %}} built-in variable is found (that is, Django is running on an {{% vendor/name %}} environment), override your previous settings.
97+
No matter what environment type we run on {{% vendor/name %}}, this file uses production settings for {{% vendor/name %}} (i.e. `DEBUG = False`).
98+
1. **Static.** `STATIC_ROOT`, and the `static` files path is updated relative to the application root on {{% vendor/name %}}.
99+
100+
1. **Secret key.** All {{% vendor/name %}} projects come with a unique hash environment variable `PLATFORM_PROJECT_ENTROPY` that can be used to update your `SECRET_KEY`.
101+
102+
1. **Databases.** When Django is running on an {{% vendor/name %}} enviroment _at runtime_, it has access to service containers like databases and caches.
103+
Every service container you configure in `.upsun/config.yaml` has a unique relationship name (`applications:<APP_NAME>:relationships:<RELATIONSHIPNAME>`).
104+
{{% vendor/name %}} automatically uses this relationship name to expose connection credentials through environment variables (for example, via `RELATIONSHIPNAME_HOST`).</br>
105+
Update `settings.py` according to the example above (which configures a PostgreSQL service), where the relationship `database` results in environment variables that are leveraged to update the `DATABASES` setting for your application.</br>
106+
You can use the exact same logic to configure `CACHES` from the `rediscache` relationship using the exposed `REDISCACHE_` environment variables to setup `django_redis.cache.RedisCache`.
107+
108+
## 4. Start the app
109+
110+
In your app configuration, locate the `web:commands:start` section and update it as follows:
111+
112+
```yaml {location=".upsun/config.yaml"}
113+
applications:
114+
myapp:
115+
...
116+
web:
117+
commands:
118+
start: "gunicorn -b unix:$SOCKET config.wsgi"
119+
upstream:
120+
socket_family: unix
121+
```
122+
123+
Note that if your Django instance requires a different web server,
124+
{{% vendor/name %}} also supports [several other options](/languages/python/server.md).
125+
126+
## 5. Configure static assets
127+
128+
To access Django's static assets, you need to add a second location to the `web:locations` section of your app configuration.
129+
Locate the `web:locations` section and add a location for `/static`:
130+
131+
```yaml {location=".upsun/config.yaml"}
132+
applications:
133+
myapp:
134+
...
135+
web:
136+
locations:
137+
"/":
138+
"passthru": true
139+
"/static":
140+
"allow": true
141+
"expires": "1h"
142+
"root": "static"
143+
```
144+
145+
## 6. Install dependencies and builds
146+
147+
Instruct {{% vendor/name %}} to install your Python and Node (if needed) dependencies.
148+
Locate the `hooks:build` section and update it as follows:
149+
150+
```yaml {location=".upsun/config.yaml"}
151+
applications:
152+
myapp:
153+
...
154+
build: |
155+
set -eux
156+
157+
pip install --upgrade pip
158+
pip install -r requirements.txt
159+
npm install
160+
npm run build
161+
```
162+
163+
Remove the `npm` steps if not required for your app's assets.
164+
Note that if your project uses a different package manager,
165+
{{% vendor/name %}} also supports [several other options](/languages/python/dependencies.md).
166+
167+
## 7. Configure the deploy phase
168+
169+
In your app configuration, locate the `deploy` section and update it as follows:
170+
171+
```yaml {location=".upsun/config.yaml"}
172+
applications:
173+
myapp:
174+
...
175+
deploy: |
176+
set -eux
177+
178+
python manage.py collectstatic --noinput
179+
python manage.py migrate
180+
```
181+
182+
## 8. Allow write access where needed
183+
184+
Since Django can require a writable locations at runtime, you need to set up writable mounts.
185+
To do so, locate the `mounts` section (currently commented), and update it as follows:
186+
187+
```yaml {location=".upsun/config.yaml"}
188+
applications:
189+
myapp:
190+
...
191+
mounts:
192+
"/staticfiles":
193+
source: "local"
194+
source_path: "static_assets"
195+
```
196+
197+
You can now commit all of the above changes and push to {{% vendor/name %}}.
198+
199+
```bash {location="Terminal"}
200+
git add .
201+
git commit -m "Add changes to complete my {{% vendor/name %}} configuration"
202+
git push
203+
```
21204

22-
- [Upsun demo application](https://console.upsun.com/projects/create-project)
23-
- [Upsun Getting started guide](/get-started/here/_index.md)
24-
- [What is Upsun?](/learn/overview)
205+
## Further resources
25206

26-
## Documentation
207+
### Documentation
27208

28209
- [Python documentation](/languages/python/)
29210
- [Managing dependencies](/languages/python/dependencies)
30211
- [Configuring web servers](/languages/python/server)
31212

32-
## Community content
213+
### Community content
33214

34215
- [Django topics](https://support.platform.sh/hc/en-us/search?utf8=%E2%9C%93&query=django)
35216
- [Python topics](https://support.platform.sh/hc/en-us/search?utf8=%E2%9C%93&query=python)
36217

37-
## Blogs
218+
### Blogs
38219

39-
- [Up(sun) and running with Django](https://upsun.com/blog/setting-up-django-on-upsun/)
220+
- [_Up(sun) and running with Django_](https://upsun.com/blog/setting-up-django-on-upsun/)
40221

41222
<!-- ## Video -->

0 commit comments

Comments
 (0)