# Django Admin Shell
A Django Web Shell using Xterm.js and Django Channels.
Note: This package depends on websockets therefore you'll need to use an ASGI application to use it. If you are not using Django channels then read through the official [Channels' documentation on installing Channels](https://channels.readthedocs.io/en/latest/installation.html), also see the [Channels' documentation on running ASGI applications](https://channels.readthedocs.io/en/latest/deploying.html).
## Demo
_The demo is from [Django.wtf's](https://django.wtf/) admin._
## Features
- Fully responsive terminal using Xterm.js.
- Accessible through the admin.
- Authentication with Django auth, configurable to allow only superusers.
- The commands written are tied to a user.
- Saves command in a new model and create favorite commands.
- Filterable command history.
- LogEntry of all commands ran.
- Custom admin site to add Terminal links to the admin.
- Full screen mode.
- Working autocomplete.
## Installation
Install the package using pip:
```bash
pip install django-admin-shellx
```
Add `django_admin_shellx` to your `INSTALLED_APPS`:
```python
INSTALLED_APPS = [
# ...
'django_admin_shellx',
# ...
]
```
The package uses websockets for real-time communication between a pseudo-shell on the server and
Xterm.js in the browser. Django doesn't handle websockets natively, so we have to deploy a second WSGI server for
this purpose.
We will have to add an ASGI configuration file for the websocket server:
```python
import os
from channels.auth import AuthMiddlewareStack
from channels.routing import ProtocolTypeRouter, URLRouter
from channels.security.websocket import AllowedHostsOriginValidator
from django.core.asgi import get_asgi_application
# Follows the path of cookiecutter-django
os.environ.setdefault("DJANGO_SETTINGS_MODULE", "config.settings.production")
# The ASGI application
django_application = get_asgi_application()
# Remember to import the urlpatters after the asgi application!
# pylint: disable=wrong-import-position
from django_admin_shellx.urls import websocket_urlpatterns
application = ProtocolTypeRouter(
{
"websocket": AllowedHostsOriginValidator(
AuthMiddlewareStack(URLRouter(websocket_urlpatterns))
),
}
)
```
When running the server in production you'll have:
1. A Django server which serves all of your traditional HTTP traffic (wsgi.py).
2. A Websocket server which serves the terminal traffic (asgi.py).
3. A reverse proxy which routes traditional traffic to the HTTP server and all websocket traffic
(**prefixed with /ws**) to your websocket server.
To start the traditional server you'll use Gunicorn as usual.
To start the websocket server you use [Daphne](https://github.com/django/daphne).
```sh
daphne config.asgi:application -b 0.0.0.0 -p 80
```
Lastly, we'll need to use a custom admin site to add a link to the terminal, add the following to your `INSTALLED_APPS`:
```python
INSTALLED_APPS = [
...
"django_admin_shellx",
"django_admin_shellx_custom_admin.apps.CustomAdminConfig",
]
```
Ensure to remove the default `admin` app from the `INSTALLED_APPS` if you are using the custom admin site.
```python
INSTALLED_APPS = [
...
# 'django.contrib.admin',
...
]
```
The above is optional and only adds a `view` button to the admin that links to the terminal. Otherwise, there will not be a link since it's not a model and can not be added to the admin. The terminal will either be accessible through the path `/admin/django_admin_shellx/terminalcommand/terminal/` and if you use the custom admin site, it will be accessible through a link in the admin.
## Usage
Head over to the admin and click on the `Terminal` link. You'll be presented with a terminal that you can use to run commands. The default commands are `./manage.py shell_plus`, `./manage.py shell` and `/bin/bash`. You can change the default commands by setting the `DJANGO_ADMIN_SHELLX_COMMAND` setting.
Each command is saved in the database and can be accessed through the admin. You can also add new commands through the admin and favorite existing commands. Each command ran is also saved as a [LogEntry](https://docs.djangoproject.com/en/dev/ref/contrib/admin/#logentry-objects).
### Settings
| Name | Description | Type | Default | Required |
|------|-------------|------|---------|:--------:|
| DJANGO_ADMIN_SHELLX_SUPERUSER_ONLY | Only allow superusers to access the admin shellx. | `boolean` | `True` | no |
| DJANGO_ADMIN_SHELLX_COMMANDS | The default commands to use when opening the terminal. | `list[list[str]]` | [["./manage.py", "shell_plus"], ["./manage.py", "shell"], ["/bin/bash"]] | no |
| DJANGO_ADMIN_SHELLX_WS_PORT | The port to use for the websocket. | `int` | None | no |
Raw data
{
"_id": null,
"home_page": "https://github.com/adinhodovic/django-admin-shellx",
"name": "django-admin-shellx",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.9",
"maintainer_email": null,
"keywords": "django, admin, terminal, shell, xterm.js",
"author": "Adin Hodovic",
"author_email": "hodovicadin@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/e7/54/5dc907f92f400b0977e7ab6dad291c2026c77cec8d1b96e9abc3ae1d1b12/django_admin_shellx-0.3.1.tar.gz",
"platform": null,
"description": "# Django Admin Shell\n\nA Django Web Shell using Xterm.js and Django Channels.\n\nNote: This package depends on websockets therefore you'll need to use an ASGI application to use it. If you are not using Django channels then read through the official [Channels' documentation on installing Channels](https://channels.readthedocs.io/en/latest/installation.html), also see the [Channels' documentation on running ASGI applications](https://channels.readthedocs.io/en/latest/deploying.html).\n\n## Demo\n\n\n_The demo is from [Django.wtf's](https://django.wtf/) admin._\n\n## Features\n\n- Fully responsive terminal using Xterm.js.\n- Accessible through the admin.\n- Authentication with Django auth, configurable to allow only superusers.\n- The commands written are tied to a user.\n- Saves command in a new model and create favorite commands.\n- Filterable command history.\n- LogEntry of all commands ran.\n- Custom admin site to add Terminal links to the admin.\n- Full screen mode.\n- Working autocomplete.\n\n## Installation\n\nInstall the package using pip:\n\n```bash\npip install django-admin-shellx\n```\n\nAdd `django_admin_shellx` to your `INSTALLED_APPS`:\n\n```python\nINSTALLED_APPS = [\n # ...\n 'django_admin_shellx',\n # ...\n]\n```\n\nThe package uses websockets for real-time communication between a pseudo-shell on the server and\nXterm.js in the browser. Django doesn't handle websockets natively, so we have to deploy a second WSGI server for\nthis purpose.\n\nWe will have to add an ASGI configuration file for the websocket server:\n\n```python\nimport os\n\nfrom channels.auth import AuthMiddlewareStack\nfrom channels.routing import ProtocolTypeRouter, URLRouter\nfrom channels.security.websocket import AllowedHostsOriginValidator\nfrom django.core.asgi import get_asgi_application\n\n# Follows the path of cookiecutter-django\nos.environ.setdefault(\"DJANGO_SETTINGS_MODULE\", \"config.settings.production\")\n\n# The ASGI application\ndjango_application = get_asgi_application()\n\n# Remember to import the urlpatters after the asgi application!\n# pylint: disable=wrong-import-position\nfrom django_admin_shellx.urls import websocket_urlpatterns\n\napplication = ProtocolTypeRouter(\n {\n \"websocket\": AllowedHostsOriginValidator(\n AuthMiddlewareStack(URLRouter(websocket_urlpatterns))\n ),\n }\n)\n```\n\nWhen running the server in production you'll have:\n\n1. A Django server which serves all of your traditional HTTP traffic (wsgi.py).\n2. A Websocket server which serves the terminal traffic (asgi.py).\n3. A reverse proxy which routes traditional traffic to the HTTP server and all websocket traffic\n (**prefixed with /ws**) to your websocket server.\n\nTo start the traditional server you'll use Gunicorn as usual.\n\nTo start the websocket server you use [Daphne](https://github.com/django/daphne).\n\n```sh\ndaphne config.asgi:application -b 0.0.0.0 -p 80\n```\n\n\nLastly, we'll need to use a custom admin site to add a link to the terminal, add the following to your `INSTALLED_APPS`:\n\n```python\nINSTALLED_APPS = [\n ...\n \"django_admin_shellx\",\n \"django_admin_shellx_custom_admin.apps.CustomAdminConfig\",\n]\n```\n\nEnsure to remove the default `admin` app from the `INSTALLED_APPS` if you are using the custom admin site.\n\n```python\nINSTALLED_APPS = [\n ...\n # 'django.contrib.admin',\n ...\n]\n```\n\nThe above is optional and only adds a `view` button to the admin that links to the terminal. Otherwise, there will not be a link since it's not a model and can not be added to the admin. The terminal will either be accessible through the path `/admin/django_admin_shellx/terminalcommand/terminal/` and if you use the custom admin site, it will be accessible through a link in the admin.\n\n## Usage\n\nHead over to the admin and click on the `Terminal` link. You'll be presented with a terminal that you can use to run commands. The default commands are `./manage.py shell_plus`, `./manage.py shell` and `/bin/bash`. You can change the default commands by setting the `DJANGO_ADMIN_SHELLX_COMMAND` setting.\n\nEach command is saved in the database and can be accessed through the admin. You can also add new commands through the admin and favorite existing commands. Each command ran is also saved as a [LogEntry](https://docs.djangoproject.com/en/dev/ref/contrib/admin/#logentry-objects).\n\n### Settings\n\n| Name | Description | Type | Default | Required |\n|------|-------------|------|---------|:--------:|\n| DJANGO_ADMIN_SHELLX_SUPERUSER_ONLY | Only allow superusers to access the admin shellx. | `boolean` | `True` | no |\n| DJANGO_ADMIN_SHELLX_COMMANDS | The default commands to use when opening the terminal. | `list[list[str]]` | [[\"./manage.py\", \"shell_plus\"], [\"./manage.py\", \"shell\"], [\"/bin/bash\"]] | no |\n| DJANGO_ADMIN_SHELLX_WS_PORT | The port to use for the websocket. | `int` | None | no |\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A Django Admin Shell",
"version": "0.3.1",
"project_urls": {
"Documentation": "https://github.com/adinhodovic/django-admin-shellx",
"Homepage": "https://github.com/adinhodovic/django-admin-shellx",
"Repository": "https://github.com/adinhodovic/django-admin-shellx"
},
"split_keywords": [
"django",
" admin",
" terminal",
" shell",
" xterm.js"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "92544a1b70563e14d516f6728ee6f87ac9ae631e616929d45458be65f694ec56",
"md5": "6c7904c4bc24e678a85ce65d710aca84",
"sha256": "5ebec39269577c1cd531ae8c8f7b57a77040e61fa34a649a5276f1401748356f"
},
"downloads": -1,
"filename": "django_admin_shellx-0.3.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "6c7904c4bc24e678a85ce65d710aca84",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.9",
"size": 101054,
"upload_time": "2024-03-29T13:06:33",
"upload_time_iso_8601": "2024-03-29T13:06:33.495549Z",
"url": "https://files.pythonhosted.org/packages/92/54/4a1b70563e14d516f6728ee6f87ac9ae631e616929d45458be65f694ec56/django_admin_shellx-0.3.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "e7545dc907f92f400b0977e7ab6dad291c2026c77cec8d1b96e9abc3ae1d1b12",
"md5": "7782cfddbb069ec5ca28e752f27497e2",
"sha256": "976f822eb988b02236acd585601e909a5f48b6806ee53586287ddff626f19ab0"
},
"downloads": -1,
"filename": "django_admin_shellx-0.3.1.tar.gz",
"has_sig": false,
"md5_digest": "7782cfddbb069ec5ca28e752f27497e2",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.9",
"size": 98928,
"upload_time": "2024-03-29T13:06:35",
"upload_time_iso_8601": "2024-03-29T13:06:35.531332Z",
"url": "https://files.pythonhosted.org/packages/e7/54/5dc907f92f400b0977e7ab6dad291c2026c77cec8d1b96e9abc3ae1d1b12/django_admin_shellx-0.3.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-03-29 13:06:35",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "adinhodovic",
"github_project": "django-admin-shellx",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"tox": true,
"lcname": "django-admin-shellx"
}
JSON
