{"id":17004210,"url":"https://github.com/ppfeufer/aa-example-plugin","last_synced_at":"2025-10-07T11:21:36.220Z","repository":{"id":57750653,"uuid":"469169800","full_name":"ppfeufer/aa-example-plugin","owner":"ppfeufer","description":"Alliance Auth Example Plugin (GitHub Version)","archived":false,"fork":false,"pushed_at":"2025-07-08T08:16:48.000Z","size":207,"stargazers_count":1,"open_issues_count":0,"forks_count":18,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-07-08T09:28:20.497Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ppfeufer.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2022-03-12T18:38:53.000Z","updated_at":"2025-07-08T08:16:51.000Z","dependencies_parsed_at":"2023-09-26T12:03:33.536Z","dependency_job_id":"f4f31be2-4395-4eac-af4f-3514f705b1fb","html_url":"https://github.com/ppfeufer/aa-example-plugin","commit_stats":{"total_commits":108,"total_committers":4,"mean_commits":27.0,"dds":0.25,"last_synced_commit":"bf4d8de3528041acb45c0f0a5102bacfc38e2a6c"},"previous_names":[],"tags_count":8,"template":false,"template_full_name":null,"purl":"pkg:github/ppfeufer/aa-example-plugin","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ppfeufer%2Faa-example-plugin","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ppfeufer%2Faa-example-plugin/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ppfeufer%2Faa-example-plugin/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ppfeufer%2Faa-example-plugin/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ppfeufer","download_url":"https://codeload.github.com/ppfeufer/aa-example-plugin/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ppfeufer%2Faa-example-plugin/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":267302181,"owners_count":24066451,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-07-27T02:00:11.917Z","response_time":82,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-10-14T04:43:04.675Z","updated_at":"2025-10-07T11:21:31.184Z","avatar_url":"https://github.com/ppfeufer.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Example Plugin App for Alliance Auth (GitHub Version)\u003ca name=\"example-plugin-app-for-alliance-auth-github-version\"\u003e\u003c/a\u003e\n\nThis is an example plugin app for [Alliance Auth](https://gitlab.com/allianceauth/allianceauth)\n(AA) that can be used as a starting point to develop custom plugins.\n\n![License](https://img.shields.io/badge/license-GPLv3-green)\n![python](https://img.shields.io/badge/python-3.8-informational)\n![django](https://img.shields.io/badge/django-3.2-informational)\n![pre-commit](https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit\u0026logoColor=white)\n\n_(These badges are examples, you can and should replace them with your own)_\n\nFor the GitLab version of this example app, please have a look over here, Erik\nKalkoken was so friendly to provide it » [Alliance Auth Example App (GitLab Version)](https://gitlab.com/ErikKalkoken/allianceauth-example-plugin)\n\n______________________________________________________________________\n\n\u003c!-- mdformat-toc start --slug=github --maxlevel=6 --minlevel=1 --\u003e\n\n- [Example Plugin App for Alliance Auth (GitHub Version)](#example-plugin-app-for-alliance-auth-github-version)\n  - [Features](#features)\n  - [How to Use It](#how-to-use-it)\n    - [Cloning From Repo](#cloning-from-repo)\n    - [Renaming the App](#renaming-the-app)\n  - [Clearing Migrations](#clearing-migrations)\n  - [Writing Unit Tests](#writing-unit-tests)\n  - [Installing Into Your Dev AA](#installing-into-your-dev-aa)\n  - [Installing Into Production AA](#installing-into-production-aa)\n  - [Contribute](#contribute)\n\n\u003c!-- mdformat-toc end --\u003e\n\n______________________________________________________________________\n\n## Features\u003ca name=\"features\"\u003e\u003c/a\u003e\n\n- The plugin can be installed, upgraded (and removed) into an existing AA\n  installation using PyInstaller.\n- It has its own menu item in the sidebar.\n- It has one view that shows a panel and some text\n\n## How to Use It\u003ca name=\"how-to-use-it\"\u003e\u003c/a\u003e\n\nTo use this example as a basis for your own development, just fork this repo and then\nclone it on your dev machine.\n\nYou then should rename the app, and then you can install it into your AA dev\ninstallation.\n\n### Cloning From Repo\u003ca name=\"cloning-from-repo\"\u003e\u003c/a\u003e\n\nFor this app, we're assuming that you have all your AA projects, your virtual\nenvironment, and your AA installation under one top folder (e.g. aa-dev).\n\nThis should look something like this:\n\n```text\naa-dev\n|- venv/\n|- myauth/\n|- aa-example-plugin\n|- (other AA projects ...)\n```\n\nThen just cd into the top folder (e.g. aa-dev) and clone the repo from your fork.\nYou can give the repo a new name right away (e.g. `aa-your-app-name`). You also want\nto create a new git repo for it.\nFinally, enable [pre-commit](https://pre-commit.com) to enable automatic code style\nchecking.\n\n```bash\ngit clone https://github.com/YourName/aa-example-plugin.git aa-your-app-name\ncd aa-your-app-name\nrm -rf .git\ngit init\npre-commit install\n```\n\n### Renaming the App\u003ca name=\"renaming-the-app\"\u003e\u003c/a\u003e\n\nBefore installing this app into your dev AA you need to rename it to something\nsuitable for your development project. Otherwise, you risk not being able to install\nadditional apps that might also be called example.\n\nHere is an overview of the places that you need to edit to adopt the name.\n\nEasiest is to just find \u0026 replace `example` with your new app name in all files\nlisted below.\n\nOne small warning about picking names: Python is a bit particular about what special\ncharacters are allowed for names of modules and packages. To avoid any pitfalls, I\nwould therefore recommend using only normal characters (a-z) in your app's name\nunless you know exactly what you're doing.\n\n| Location                                 | Description                                                                            |\n| ---------------------------------------- | -------------------------------------------------------------------------------------- |\n| `./example/`                             | Folder name                                                                            |\n| `./example/static/example/`              | Folder name                                                                            |\n| `./example/templates/example/`           | Folder name                                                                            |\n| `./pyproject.cfg`                        | Update module name for version import, update package name, update title, author, etc. |\n| `./example/apps.py`                      | App name                                                                               |\n| `./example/__init__.py`                  | App name                                                                               |\n| `./example/auth_hooks.py`                | Menu hook config incl. icon and label of your app's menu item appearing in the sidebar |\n| `./example/models.py`                    | App name                                                                               |\n| `./example/urls.py`                      | App name                                                                               |\n| `./example/views.py`                     | Permission name and template path                                                      |\n| `./example/templates/example/base.html`  | Title of your app to be shown in all views and as title in the browser tab             |\n| `./example/templates/example/index.html` | Template path                                                                          |\n| `./testauth/local.py`                    | App name in `PACKAGE` constant                                                         |\n| `./.coveragerc`                          | App name                                                                               |\n| `./MANIFEST.in`                          | App name                                                                               |\n| `./README.md`                            | Clear content                                                                          |\n| `./LICENSE`                              | Replace with your own license                                                          |\n| `./tox.ini`                              | App name                                                                               |\n| `./.isort.cfg`                           | App name for `import_heading_firstparty`                                               |\n| `./Makefile`                             | App name and package name                                                              |\n\n## Clearing Migrations\u003ca name=\"clearing-migrations\"\u003e\u003c/a\u003e\n\nInstead of renaming your app in the migrations, it's easier to just recreate them\nlater in the process. For this to work, you need to delete the old migration files in\nyour `migrations` folder.\n\n```bash\nrm your-app-name/migrations/0001_initial.py\nrm -rf your-app-name/migrations/_pycache\n```\n\n## Writing Unit Tests\u003ca name=\"writing-unit-tests\"\u003e\u003c/a\u003e\n\nWrite your unit tests in `your-app-name/tests/` and make sure that you use a \"test\\_\"\nprefix for files with your unit tests.\n\n## Installing Into Your Dev AA\u003ca name=\"installing-into-your-dev-aa\"\u003e\u003c/a\u003e\n\nOnce you've cloned or copied all files into place and finished renaming the app,\nyou're ready to install it to your dev AA instance.\n\nMake sure you're in your venv. Then install it with pip in editable mode:\n\n```bash\npip install -e aa-your-app-name\n```\n\nFirst add your app to the Django project by adding the name of your app to\nINSTALLED_APPS in `settings/local.py`.\n\nNext, we will create new migrations for your app:\n\n```bash\npython manage.py makemigrations\n```\n\nThen run a check to see if everything is set up correctly.\n\n```bash\npython manage.py check\n```\n\nIn case they're errors make sure to fix them before proceeding.\n\nNext, perform migrations to add your model to the database:\n\n```bash\npython manage.py migrate\n```\n\nFinally, restart your AA server and that's it.\n\n## Installing Into Production AA\u003ca name=\"installing-into-production-aa\"\u003e\u003c/a\u003e\n\nTo install your plugin into a production AA, run this command within the virtual\nPython environment of your AA installation:\n\n```bash\npip install git+https://github.com/YourName/aa-your-app-name\n```\n\nAlternatively, you can create a package file and manually upload it to your\nproduction AA:\n\n```bash\npip install build\npython -m build\n```\n\nYou'll find the package under `./dist/aa-your-app-name.tar.gz` after this.\n\nInstall your package directly from the package file:\n\n```bash\npip install aa-your-app-name.tar.gz\n```\n\nThen add your app to `INSTALLED_APPS` in `settings/local.py`, run migrations and\nrestart your allianceserver.\n\n## Contribute\u003ca name=\"contribute\"\u003e\u003c/a\u003e\n\nIf you've made a new app for AA, please consider sharing it with the rest of the\ncommunity. For any questions on how to share your app, please contact the AA devs on\ntheir Discord. You find the current community creations\n[here](https://gitlab.com/allianceauth/community-creations).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fppfeufer%2Faa-example-plugin","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fppfeufer%2Faa-example-plugin","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fppfeufer%2Faa-example-plugin/lists"}