Fediversity/panel/README.md

# Fediversity Panel

The Fediversity Panel is a web service for managing Fediversity deployments with a graphical user interface, written in Django.

## Development

- To obtain all tools related to this project, enter the development environment with `nix-shell`.

  If you want to do that automatically on entering this directory:

  - [Set up `direnv`](https://github.com/nix-community/nix-direnv#installation)
  - Run `direnv allow` in the directory where repository is stored on your machine

    > **Note**
    >
    > This is a security boundary, and allows automatically running code from this repository on your machine.

- Run NixOS integration tests and Django unit tests:

  ```bash
  nix-build -A tests
  ```

- List all available Django management commands with:

  ```shell-session
  manage
  ```

- Run the server locally

  ```shell-session
  manage runserver
  ```

- Whenever you add a field in the database schema, run:

  ```console
  manage makemigrations
  ```

  Then before starting the server again, run:

  ```
  manage migrate
  ```
scaffold Django web service This setup is greatly inspired by the one used for [0], although with notable modifications, such as: - a SASS preprocessor and CSS compressor - more streamlined NixOS integration tests - cleaned up service configuration - a few notes on how to do things better in the future [0]: https://github.com/Nix-Security-WG/nix-security-tracker/ Apart from cloning the Nix setup, there were additional steps: - Create an empty `src` directory, since the package requires it - In the development shell, run `django-admin startproject panel src` Note that while you can already do ```bash manage migrate manage runserver ``` the NixOS integration tests will fail, since `settings.py` needs careful massaging to expose knobs that can be turned from our systemd wrapper. The required changes are introduced in the next commit to make them observable. Noteworthy related work: - https://github.com/sephii/django.nix Rather mature setup with a clean interface, uses Caddy as reverse proxy. - https://git.dgnum.eu/mdebray/djangonix A work-in-progress attempt to capture more moving parts through the module system, in particular secrets. - https://github.com/DavHau/django-nixos Out of date and somewhat simplistic, but serves as a reasonable example for what can be done I chose the variant I'm intimately familiar with in order to be able to pass on knowledge or help with maintenance. But for the future I strongly recommend picking the good bits from the other implementations that control complexity in static configuration parts through Nix expressions. 2025-02-12 23:51:55 +01:00			`# Fediversity Panel`

			`The Fediversity Panel is a web service for managing Fediversity deployments with a graphical user interface, written in Django.`

			`## Development`

			- To obtain all tools related to this project, enter the development environment with `nix-shell`.

			`If you want to do that automatically on entering this directory:`

			- [Set up `direnv`](https://github.com/nix-community/nix-direnv#installation)
			- Run `direnv allow` in the directory where repository is stored on your machine

			`> Note`
			`>`
			`> This is a security boundary, and allows automatically running code from this repository on your machine.`

			`- Run NixOS integration tests and Django unit tests:`

			```bash
			`nix-build -A tests`
			```

			`- List all available Django management commands with:`

			```shell-session
			`manage`
			```

			`- Run the server locally`

			```shell-session
			`manage runserver`
			```

			`- Whenever you add a field in the database schema, run:`

			```console
			`manage makemigrations`
			```

			`Then before starting the server again, run:`

			```
			`manage migrate`
			```