Development
You will likely want to keep open multiple terminal windows while working on nyan.
Install requirements
The following commands are required:
Create Minikube cluster
A Minikube deployment of dsri nyan can be found in the
deploy/minikube directory.
First, create a Minikube cluster, setting the CPU and memory limits to values appropriate for your system (the default is 2 CPUs and 4GB memory):
Note
--cni=cilium allows NetworkPolicy resources to be used in Minikube.
minikube start --cni=cilium --cpus 4 --memory 8GB
Wait for the cluster to be created:
$ minikube start --cpus 4 --memory 8GB
😄 minikube v1.33.1 on Debian bookworm/sid
✨ Automatically selected the docker driver. Other choices: virtualbox, ssh
📌 Using Docker driver with root privileges
👍 Starting "minikube" primary control-plane node in "minikube" cluster
🚜 Pulling base image v0.0.44 ...
🔥 Creating docker container (CPUs=4, Memory=8192MB) ...
🐳 Preparing Kubernetes v1.30.0 on Docker 26.1.1 ...
▪ Generating certificates and keys ...
▪ Booting up control plane ...
▪ Configuring RBAC rules ...
🔗 Configuring bridge CNI (Container Networking Interface) ...
🔎 Verifying Kubernetes components...
▪ Using image gcr.io/k8s-minikube/storage-provisioner:v5
🌟 Enabled addons: storage-provisioner, default-storageclass
🏄 Done! kubectl is now configured to use "minikube" cluster and "default" namespace by default
Verify that the cluster is fully initialized by ensuring that all cluster pods are running:
kubectl get pod -A
$ kubectl get pod -A
NAMESPACE NAME READY STATUS RESTARTS AGE
kube-system coredns-7db6d8ff4d-ftngl 1/1 Running 0 2m27s
kube-system etcd-minikube 1/1 Running 0 2m41s
kube-system kube-apiserver-minikube 1/1 Running 0 2m41s
kube-system kube-controller-manager-minikube 1/1 Running 0 2m43s
kube-system kube-proxy-mh92p 1/1 Running 0 2m28s
kube-system kube-scheduler-minikube 1/1 Running 0 2m41s
kube-system storage-provisioner 1/1 Running 1 (117s ago) 2m40s
Run minikube tunnel
On completion, you'll want to run another minikube command, which you will keep open while working on nyan:
minikube tunnel
$ minikube tunnel
[sudo] password for user:
Status:
machine: minikube
pid: 29444
route: 10.96.0.0/12 -> 192.168.49.2
minikube: Running
services: []
errors:
minikube: no errors
router: no errors
loadbalancer emulator: no errors
Warning
Since you will be prompted for sudo, it's tempting to do this:
# Don't do this
sudo minikube tunnel
This leaves Minikube unable to find the profile for the cluster you created, so wait to be prompted instead:
# Do this
minikube tunnel
Deploy OpenTofu resources
Change to the deploy/minikube directory when running tofu commands:
cd deploy/minikube
On first checkout, you'll need to run tofu init:
tofu init
$ tofu init
Initializing the backend...
Initializing provider plugins...
- Reusing previous version of opentofu/local from the dependency lock file
- Reusing previous version of opentofu/random from the dependency lock file
- Reusing previous version of opentofu/helm from the dependency lock file
...
With OpenTofu initialized, you can now execute the deployment:
tofu apply
$ tofu apply
OpenTofu used the selected providers to generate the following execution plan. Resource actions are indicated with
the following symbols:
+ create
...
...
...
Do you want to perform these actions?
OpenTofu will perform the actions described above.
Only 'yes' will be accepted to approve.
Enter a value:
Type yes to proceed with the apply:
Enter a value: yes
kubernetes_namespace.ingress: Creating...
...
...
...
helm_release.nyan_postgresql: Creation complete after 56s [id=nyan-postgresql]
Apply complete! Resources: 10 added, 0 changed, 0 destroyed.
...
Important
Ensure that the minikube tunnel command is still
running, otherwise tofu apply will hang when deploying the ingress
controller Helm chart.
This deployment creates a scaffolding for your various local experiments to slot
into. It includes deployments for PostgreSQL and valkey, so that your
application has stable backing services to use. These new additions are visible
by running kubectl get pod -A again:
$ kubectl get pod -A
NAMESPACE NAME READY STATUS RESTARTS AGE
ingress ingress-nginx-ingress-controller-d46694fcd-hbqr4 1/1 Running 0 2m23s
ingress ingress-nginx-ingress-controller-default-backend-7f9f59b44n2j8l 1/1 Running 0 2m23s
kube-system coredns-7db6d8ff4d-ftngl 1/1 Running 0 18m
kube-system etcd-minikube 1/1 Running 0 18m
kube-system kube-apiserver-minikube 1/1 Running 0 18m
kube-system kube-controller-manager-minikube 1/1 Running 0 18m
kube-system kube-proxy-mh92p 1/1 Running 0 18m
kube-system kube-scheduler-minikube 1/1 Running 0 18m
kube-system storage-provisioner 1/1 Running 1 (17m ago) 18m
nyan nyan-postgresql-0 1/1 Running 0 2m22s
nyan nyan-valkey-master-0 1/1 Running 0 2m22s
Change back to the project root directory to continue:
cd ../..
Run nyan as a cluster app
At this point, you can test the nyan app immediately by using the included Helm chart.
The previous tofu apply command creates a
values.yaml file in the deploy/minikube directory. This can be used to
deploy the nyan Helm chart pre-configured for this deployment.
A skaffold configuration is provided that installs your local Helm chart to the Minikube cluster with no additional settings needed:
skaffold dev --port-forward
A Makefile target is provided that does the same:
make skaffold
$ skaffold dev --port-forward
Generating tags...
- nyan -> nyan:d9474e9-dirty
Checking cache...
- nyan: Not found. Building
Starting build...
Found [minikube] context, using local docker daemon.
Building [nyan]...
Target platforms: [linux/amd64]
...
...
...
Deployments stabilized in 6.107 seconds
Port forwarding service/nyan-app in namespace nyan, remote port 8080 -> http://127.0.0.1:8080
Listing files to watch...
- nyan
Press Ctrl+C to exit
Watching for changes...
[nyan] Operations to perform:
[nyan] Apply all migrations: account, admin, auditlog, auth, contenttypes, core, db, mfa, sessions, socialaccount, users, usersessions
[nyan] Running migrations:
[nyan] No migrations to apply.
[nyan] [2024-10-25 19:00:47 +0000] [1] [INFO] Starting gunicorn 23.0.0
[nyan] [2024-10-25 19:00:47 +0000] [1] [INFO] Listening at: http://0.0.0.0:8080 (1)
[nyan] [2024-10-25 19:00:47 +0000] [1] [INFO] Using worker: sync
[nyan] [2024-10-25 19:00:47 +0000] [7] [INFO] Booting worker with pid: 7
Once the application is stable (when it says "Watching for changes"), you can browse to the application UI:
Create a superuser account
The superuser account must be created to proceed any further. To do that, we
must access the manage.py command while skaffold is running.
Retrieve a list of all available management commands:
kubectl exec -it -n nyan deployment/nyan-app -- ./manage.py
The createsuperuser command is the first one to run. Follow the on-screen
prompts to create the first account:
Important
Use a valid email, as this app will include support for transactional email at some point.
kubectl exec -it -n nyan deployment/nyan-app -- ./manage.py createsuperuser
$ kubectl exec -it -n nyan deployment/nyan-app -- ./manage.py createsuperuser
Username: user
Email address: [email protected]
Password:
Password (again):
Superuser created successfully.
Access the admin interface
The admin interface will be accessible at the
/admin/ URL path:
Log in. When asked to verify your email, check the console logs for skaffold
for the "email" you've received:
[nyan] Content-Type: text/plain; charset="utf-8"
[nyan] MIME-Version: 1.0
[nyan] Content-Transfer-Encoding: 7bit
[nyan] Subject: [Nyan] Please Confirm Your Email Address
[nyan] From: webmaster@localhost
[nyan] To: [email protected]
[nyan] Date: Sat, 26 Oct 2024 00:01:52 -0000
[nyan] Message-ID: <172990091262.7.9414480326994878345@nyan-app-98bcc98d7-472kk>
[nyan]
[nyan] Hello from localhost:8080!
[nyan]
[nyan] You're receiving this email because user breer has given your email address to register an account on localhost:8080.
[nyan]
[nyan] To confirm this is correct, go to http://localhost:8080/user/confirm-email/MQ:1t4UFc:Puajjg2JXLLVKOhl8cDUfUuKigOY3wBUfrh_2MHd5xI/
[nyan]
[nyan] Thank you for using localhost:8080!
[nyan] localhost:8080
[nyan] -------------------------------------------------------------------------------
Click the link in the email to confirm your account, and navigate to the
/admin/ path once more:
Log in again and you'll be able to access the admin interface.
Run nyan via the local development server
It's possible to run nyan via Django's local development server, manage.py
runserver.. This allows you to take advantage of live reloading and various
debug facilities.
Set up a virtual environment
Use the included Makefile target to set up a virtual environment:
make setup
Source the virtual environment:
. venv/bin/activate
Create a settings.ini file
The previous tofu apply command creates a
settings.ini file in the deploy/minikube directory. This file looks
something like the following:
[settings]
NYAN_SECRET_KEY = XXXXXX
NYAN_DATABASE_URL = postgres://nyan:XXXXXX@localhost:5432/nyan
NYAN_CACHE_URL = redis://:XXXXXX@localhost:6379/0
NYAN_BROKER_URL = redis://:XXXXXX@localhost:6379/0
NYAN_SITE_ENVIRONMENT = local
Copy deploy/minikube/settings.ini to the project root directory where
manage.py will be executed from:
cp deploy/minikube/settings.ini settings.ini
A Makefile target is provided to start the local development environment. This includes:
-
Forwarding ports for PostgreSQL and valkey
-
Starting a generic celery worker and flower instance
-
Starting Django's development server with
DEBUGenabled -
Compiling CSS with sass
make local
Enable live reloading
Adding the following to settings.ini causes your browser to reload whenever a
change is made to source:
NYAN_LIVE_RELOAD = true