Cobalt for Pork Chops

Cobalt Chemical Symbol Pork Chops

Cobalt for Pork Chops#

About

The Pork Chop pages are intended to help people coming into Cobalt from a bridge background who are not experienced Django developers. They are NOT required reading for Django developers.

If you have recently got involved in Cobalt, then before you start carrying on like a pork chop, read this.

Cobalt is written in Django. Yes, it could have been written in whatever your favourite tool is but it’s not. To understand this better you can read the ABF Technology Strategy which describes why Cobalt was built and the ABF Technology Strategy Implementation Implementation which describes the choice of tools.

Both of these are now somewhat out of date, but should give you at least an overview of the thought processes.

If you aren’t familiar with Django then it is recommended that you read Django for Pork Chops. This assumes you know Python, if you don’t then you should first read Python for Pork Chops.

Basic Architecture#

Cobalt tries to be as simple and basic a Django application as possible. It uses Postgres (although there are no Postgres-specific features used so it should work with any database backend). Each logical function has its own application.

We use HTMX so there is no frontend framework to deal with. All of the frontend HTML is generated by Django through the default template engine.

For the Australian Bridge Federation (ABF), Cobalt is deployed on AWS Elastic Beanstalk. You will find some code relating to AWS within the Cobalt code base, but you can deploy Cobalt on any platform that you like. The only small exception to this is that Cobalt uses AWS Simple Email Service (SES) to track emails. You can deploy Cobalt on any other platform and still use SES or you can live without the tracking features.

Tools#

With the utils application in Cobalt there are a number of tools that can help with development activities. See Utilities Application for details.

  • cgit is a set of tools for working with github and AWS Elastic Beanstalk.

  • Inside the aws folder of utils you can find tools related to building environments on AWS

Development#

Main document: Development Approach.

I don’t use Windows very much, most of the development of Cobalt has been done on a Mac. Some development however, was done successfully on Windows up to a point. I switched from native Windows development, to using Windows Linux Subsystem after a while. The intermittent problems I had, mainly with file permissions, went away when I started using WLS.

If you do want to develop on Windows that is fine, I recommend using WLS, but you don’t have to, just watch out for Windows specific problems, especially related to file permissions.

Note also that most of the command line utilities will only work on Unix style environments.

The Banned List#

Some things are not currently permitted in Cobalt, here is the list.

  • Django Rest Framework or DRF is a very popular framework for building APIs. Our architecture does not require a separate back and front end so DRF is not required. This is still a contentious area mainly due to the large investment that many projects have in this architecture. With the introduction of game changing technologies such as HTMX, we do not expect this to be contentious for long. We do have a requirement for a genuine API to external systems and for this we use Django Ninja which is very simple to use.

  • Class Based View are the work of the Devil. If you want to make your code totally unmaintainable then they are highly recommended.

  • Docker probably makes sense in some odd use cases. Obviously, you can deploy Cobalt however you like and develop however you like, but for the number of developers we have and the deployment environments that we use, it is totally unnecessary, so please keep it out of the code base.

  • Celery requires a message bus such as Redis to work which adds additional infrastructure dependencies to our already complicated environment. If we ever get a proper requirement then we could add it, but for now cron works perfectly.

Quirks and Things to Know#

Static Files#

Normally for a Django project you would add /static to .gitignore and run collectstatic as part of the deployment process on each server. For Elastic Beanstalk with manifeststaticfilesstorage that will not work. You need to ensure that collectstatic is run within the development environment as Elasticbeanstalk gives all files the same create date which means that manifeststaticfilesstorage can’t tell which is the most recent one and doesn’t know which file to use.

FAQ#

Q: I have looked at the code and bits of it don’t match what the documentation says. How come?

A: The documentation reflects what we would like the code to look like and what we are building going forward. There are still bits of code that were build in a different style (especially non-HTMX code) which could be there for several years before they get re-done.

Contents