You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
@@ -6,28 +6,256 @@ A Django-based database-driven web application, to track the progress of project
6
6
7
7
This repo contains the source code of the application. [Run the application from source](./dashboard#readme)
8
8
9
-
This repo also contains the source code of a Kubernetes charm for operating the application as part of a Juju deployment.
10
-
To learn about Juju and charms, see https://juju.is/docs.
9
+
This repo also contains the source code of a Kubernetes charm for operating the application as part of a Juju deployment. To learn about Juju and charms, see https://juju.is/docs.
11
10
12
-
> [!IMPORTANT]
11
+
> [!IMPORTANT]
13
12
> To use the dashboard charm in a real Juju deployment, see [TODO: docs on Charmhub] instead of this repo.
14
13
> This repo is the right place to look if you'd like to test the charm, customise it for your own purposes, or contribute to development!
15
14
15
+
## Deploy the dashboard on your machine
16
16
17
-
##Deploy the charm on your machine
17
+
### Prepare your environment
18
18
19
-
Work in progress. Aspects to cover:
20
-
- Minimal steps to get the application running from scratch
21
-
- Set up Juju and craft tools, pack rock, pack charm, deploy charm.
22
-
Before packing the rock, run:
19
+
1. Follow the "Set things up" instructions in [Write your first Kubernetes charm for a Django app](https://canonical-charmcraft.readthedocs-hosted.com/en/latest/tutorial/kubernetes-charm-django/). These instructions will guide you through installing the required tools.
20
+
21
+
You can stop following the setup instructions after you've installed Juju and bootstrapped a development controller.
22
+
23
+
At this point, you should have a shell session inside a Multipass virtual machine called `charm-dev`. Continue using your `charm-dev` shell session until you're ready to [open the dashboard in your browser](#open-the-dashboard-in-your-browser).
3. Modify the dashboard application so that it takes its configuration from environment variables and expects a PostgreSQL database instead of an SQLite database:
- Configure charm to work without ingress, in debug mode
28
-
- Open the dashboard in your browser
29
-
- Load sample data
30
38
39
+
For illustration, compare `DATABASES` in [settings.py (modified)](./dashboard_rock_patch/dashboard/settings.py) and [settings.py (original)](./dashboard/dashboard/settings.py).
40
+
41
+
4. Create a "model" in Juju:
42
+
43
+
``` { name=create-model }
44
+
juju add-model web-k8s
45
+
```
46
+
47
+
You can think of the model as a unified workspace for the dashboard application and related applications, including a PostgreSQL database.
48
+
49
+
After creating the model, you should see the following output:
50
+
51
+
> ```
52
+
> Added 'web-k8s' model on microk8s/localhost with credential 'microk8s' for user 'admin'
53
+
> ```
54
+
55
+
5. Check the architecture of your machine:
56
+
57
+
``` { name=check-architecture }
58
+
dpkg --print-architecture
59
+
```
60
+
61
+
If the output is not `amd64`, you'll need to adjust some of the commands in this README. For example, if the output is `arm64`, you'll need to replace `amd64` by `arm64`.
62
+
63
+
6. Configure the Juju model to match the architecture of your machine:
64
+
65
+
``` { name=configure-model }
66
+
juju set-model-constraints -m web-k8s arch=amd64 # remember to replace amd64 if needed!
67
+
```
68
+
69
+
### Create a container image for the application
70
+
71
+
``` { name=create-image }
72
+
cd ~/dashboard
73
+
rockcraft pack
74
+
```
75
+
76
+
The application will run in a Kubernetes cluster, so we need a container image for the application. The `rockcraft` command uses [Rockcraft](https://documentation.ubuntu.com/rockcraft/en/latest/) to create a "rock" image that is compliant with the [Open Container Initiative](https://opencontainers.org/) format.
77
+
78
+
Creating the container image might take several minutes, so this is a good point to take a break. When you return, you should see the following output:
79
+
80
+
> ```
81
+
> Packed dashboard_0.7_amd64.rock
82
+
> ```
83
+
84
+
### Create a charm
85
+
86
+
``` { name=create-charm }
87
+
cd ~/dashboard/charm
88
+
charmcraft pack
89
+
```
90
+
91
+
In essence, the charm is a Python wrapper for the dashboard application. It's also common to call charms "operators". The dashboard charm receives information from Juju about related applications (in our case, a PostgreSQL database) and how we'd like the dashboard to be configured, then acts appropriately in the dashboard application's container.
92
+
93
+
Creating the charm might take several minutes, so this is another good point to take a break. When you return, you should see the following output:
The `rockcraft.skopeo` command makes the container image available to Juju.
111
+
112
+
Deploying the charm adds it to our Juju model. At a high level, this does the following:
113
+
114
+
- Enables the dashboard application to discover related applications, including a PostgreSQL database.
115
+
116
+
- Runs the container image that we created for the dashboard application. There's no database yet, so this won't actually start the dashboard's web server. The charm will automatically start the web server when we integrate the dashboard with a database.
117
+
118
+
After deploying the charm, you should see the following output:
119
+
120
+
> ```
121
+
> Located local charm "dashboard", revision 0
122
+
> Deploying "dashboard" from local charm "dashboard", revision 0 on ubuntu@22.04/stable
123
+
> ```
124
+
125
+
### Configure the dashboard
126
+
127
+
``` { name=configure-dashboard }
128
+
juju config dashboard django-debug=true
129
+
juju config dashboard django-allowed-hosts='*'
130
+
```
131
+
132
+
These commands tell Juju which configuration values to use when the charm starts the dashboard's web server. We're using `django-debug=true` and `django-allowed-hosts='*'` to make it easier to access the dashboard for testing; you wouldn't use these values in a production deployment.
133
+
134
+
### Deploy a PostgreSQL charm
135
+
136
+
```{ name=deploy-postgres }
137
+
juju deploy postgresql-k8s --trust
138
+
```
139
+
140
+
### Wait for the charms to finish deploying
141
+
142
+
```{ name=watch-status }
143
+
juju status --watch 1s
144
+
```
145
+
146
+
This command displays a status report that updates every second.
147
+
148
+
Deploying the charms might take several minutes. Wait until the status of the `dashboard` app is "blocked" and the status of `postgresql-k8s` app is "active":
149
+
150
+
> ```
151
+
> Model Controller Cloud/Region Version SLA Timestamp
> postgresql-k8s/0* active idle 10.1.179.5 Primary
161
+
> ```
162
+
163
+
To exit the status report, press <kbd>Ctrl</kbd> + <kbd>C</kbd>.
164
+
165
+
### Integrate the dashboard with PostgreSQL
166
+
167
+
``` { name=integrate-charms }
168
+
juju integrate dashboard postgresql-k8s
169
+
```
170
+
171
+
When you run this command, the dashboard charm does the following:
172
+
173
+
- Receives information from Juju about the PostgreSQL database, including its location on the network, username, and password.
174
+
175
+
- Connects to the dashboard application's container and starts the dashboard's web server, with the database information in environment variables. The dashboard charm also sets environment variables for the configuration values that we specified in [Configure the dashboard](#configure-the-dashboard).
176
+
177
+
This enables the dashboard's web server to directly interact with the database.
178
+
179
+
### Check the status of the dashboard
180
+
181
+
```{ name=check-dashboard-status }
182
+
juju status dashboard
183
+
```
184
+
185
+
You should see the following output:
186
+
187
+
> ```
188
+
> Model Controller Cloud/Region Version SLA Timestamp
> App Version Status Scale Charm Channel Rev Address Exposed Message
192
+
> dashboard active 1 dashboard 0 10.152.183.219 no
193
+
>
194
+
> Unit Workload Agent Address Ports Message
195
+
> dashboard/0* active idle 10.1.179.60
196
+
> ```
197
+
198
+
### Open the dashboard in your browser
199
+
200
+
1. Grab the address of the `dashboard/0` unit from Juju's status report. In our example in [Check the status of the dashboard](#check-the-status-of-the-dashboard), the address is `10.1.179.60`.
201
+
202
+
3. Open a terminal on your machine. You'll complete the rest of this section outside your `charm-dev` virtual machine.
203
+
204
+
3. Display information about your `charm-dev` virtual machine:
205
+
206
+
```
207
+
multipass info charm-dev
208
+
```
209
+
210
+
You should see the following output:
211
+
212
+
> ```
213
+
> Name: charm-dev
214
+
> State: Running
215
+
> Snapshots: 0
216
+
> IPv4: 10.35.173.143
217
+
> 10.1.179.0
218
+
> (more lines)
219
+
> ```
220
+
221
+
4. Grab the first IPv4 address listed. This is the address of your `charm-dev` virtual machine. In our example, the address is `10.35.173.143`.
222
+
223
+
5. Make it possible to access the dashboard application's container:
224
+
225
+
```
226
+
sudo ip route add 10.1.179.0/24 via 10.35.173.143 # remember to replace the addresses!
227
+
```
228
+
229
+
- Replace `10.1.179` by the first three numbers in the address from step 1.
230
+
- Replace `10.35.173.143` by the address from step 4.
231
+
232
+
6. Open `http://<unit>:8000` in your browser, where `<unit>` is the address from step 1. In our example, that would be `http://10.1.179.60:8000`.
233
+
234
+
You should see the dashboard in your browser. Congratulations!
235
+
236
+
### Explore further
237
+
238
+
- To load the sample data that comes with the dashboard, run the following command inside your `charm-dev` virtual machine:
239
+
240
+
``` { name=load-sample-data }
241
+
juju run dashboard/0 load-sample-data
242
+
```
243
+
244
+
This uses a Juju "action" to run [manage.py](./dashboard/manage.py) inside the dashboard application's container. For technical details, see [TODO: doc in progress].
245
+
246
+
- To inspect the configuration of the dashboard's web server, run the following commands inside your `charm-dev` virtual machine:
247
+
248
+
``` {name=inspect-server }
249
+
# For convenience later, install yq to help display YAML:
250
+
which yq > /dev/null 2>&1
251
+
if [ $? -ne 0 ]; then sudo snap install yq; fi
252
+
# Ask the Pebble service manager to tell us whether the web server is active:
0 commit comments