| Name | keystone-api JSON |
| Version |
0.3.11
JSON |
| download |
| home_page | None |
| Summary | A REST API for managing user resource allocations on HPC systems. |
| upload_time | 2024-05-15 19:48:17 |
| maintainer | None |
| docs_url | None |
| author | Daniel Perrefort |
| requires_python | <4.0,>=3.11 |
| license | None |
| keywords |
pitt
crc
hpc
django
|
| VCS |
|
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# Keystone API
[](https://app.codacy.com?utm_source=gh&utm_medium=referral&utm_content=&utm_campaign=Badge_grade)
The backend REST API for the Keystone allocation management dashboard.
## Installation
To install the Keystone API, choose from one of the following options.
### Using Docker
Using Docker is the recommended method for building and deploying application instances.
The most recent image can be pulled from the GitHub container registry:
```bash
docker pull ghcr.io/pitt-crc/keystone-api
docker run -p 8000:8000 ghcr.io/pitt-crc/keystone-api
```
Alternatively, the latest development version can be built directly from source:
```bash
git clone https://github.com/pitt-crc/keystone-api
docker build -t keystone-api:develop keystone-api
docker run -p 8000:8000 keystone-api:develop
```
The container will automatically launch a fully functioning API server.
If the container is being launched for the first time, you will need to manually create the first user account.
To do so, execute the following command with the appropriate container name and follow the onscreen prompts.
```bash
docker exec -it [CONTAINER NAME] keystone-api createsuperuser
```
The default container instance is *not* suitable for full production out of the box.
See the [Settings](#settings) section for a complete overview of configurable options and recommended settings.
### Installing from PyPI
Installing the Keystone-API Python package is only recommended as a fallback for situations where using Docker is not feasible.
Before proceeding with the installation, the following dependencies must be met:
- A running Celery instance
- A running Celery Beat instance
- A running Redis database
The following dependencies are optional:
- A running PostgreSQL database (if using PostgreSQL instead of SQLite)
- LDAP development binaries (if using LDAP authentication)
In keeping with best practice, it is recommended to install packages into a dedicated virtual environment:
```bash
conda create -n keystone-api python=3.11
conda activate keystone-api
```
The package and its dependencies are pip installable.
```bash
pip install keystone-api
```
If the installation was successful, the packaged CLI tool will be available in your working environment.
Use the `--help` option to view the available commands.
```bash
keystone-api --help
```
The following example will set up the project database, create an admin user account, and launch the
API server in debug mode. As a general rule, debug mode should **never** be enabled in production.
```bash
keystone-api migrate
keystone-api createsuperuser
DEBUG=true keystone-api runserver
```
#### Enabling Autocomplete
The `keystone-api` utility does not support tab autocompletion by default.
To enable this feature, use the `enable_autocomplete` command:
```bash
keystone-api enable_autocomplete
```
## Settings
Application settings are configurable as environmental variables.
Individual settings are listed below by category and use case.
### Security
Improperly configuring these settings can introduce dangerous vulnerabilities and may damage your production deployment.
Administrators should adhere to the following general guidelines:
- Ensure your deployment is isolated behind a web proxy with proper HTTPS handling
- Always define the `SECURE_ALLOWED_HOSTS` list using a restrictive collection of domain patterns
- Avoid issuing session/CSRF tokens over unsecured connections by enabling `SECURE_SESSION_TOKENS`
- Always use a secure `SECURE_SECRET_KEY` value to ensure proper request signing across application instances/restarts
- Consider using HTTP Strict Transport Security (HSTS) to enforce the use of HTTPS
The `SECURE_SECRET_KEY` value may be changed at any given time. However, doing so may invalidate any active user
sessions and require users to reauthenticate.
| Setting Name | Default Value | Description |
|---------------------------------|-----------------------|---------------------------------------------------------|
| `SECURE_SECRET_KEY` | Randomly generated | Secret key used to enforce cryptographic signing. |
| `SECURE_ALLOWED_HOSTS` | `localhost,127.0.0.1` | Comma-separated list of accepted host/domain names. |
| `SECURE_SSL_REDIRECT` | `False` | Automatically redirect all HTTP traffic to HTTPS. |
| `SECURE_SESSION_TOKENS` | `False` | Only issue session/CSRF tokens over secure connections. |
| `SECURE_CSRF_ORIGINS` | `[]` | Domains (with protocol) to accept CSRF headers from. |
| `SECURE_HSTS_SECONDS` | `0` (Disabled) | HSTS cache duration in seconds. |
| `SECURE_HSTS_SUBDOMAINS` | `False` | Enable HSTS for subdomains. |
| `SECURE_HSTS_PRELOAD` | `False` | Enable HSTS preload functionality. |
| `SECURE_ACCESS_TOKEN_LIFETIME` | `300` (5 Minutes) | JWT Access token lifetime in seconds. |
| `SECURE_REFRESH_TOKEN_LIFETIME` | `86400` (1 Day) | JWT Refresh token lifetime in seconds. |
### General Configuration
The following settings configure varius aspects of Keystone's backend behavior.
Keystone uses various static files to facilitate operation and support user requests.
By default, these files are stored in subdirectories of the installed application directory (`<app>`).
| Setting Name | Default Value | Description |
|---------------------------|---------------------------|---------------------------------------------------------------------------------------------------|
| `CONFIG_TIMEZONE` | `UTC` | The application timezone. |
| `CONFIG_STATIC_DIR` | `<app>/static_files` | Where to store internal static files required by the application. |
| `CONFIG_UPLOAD_DIR` | `<app>/upload_files` | Where to store file data uploaded by users. |
| `CONFIG_LOG_RETENTION` | 30 days | How long to store log records in seconds. Set to 0 to keep all records. |
| `CONFIG_LOG_LEVEL` | `WARNING` | Only record logs above this level (`CRITICAL`, `ERROR`, `WARNING`, `INFO`, `DEBUG`, or `NOTSET`). |
### API Throttling
API settings are used to throttle incoming API requests against a maximum limit.
Limits are specified as the maximum number of requests per `day`, `minute`, `hour`, or `second`.
| Setting Name | Default Value | Description |
|---------------------------|--------------------------|---------------------------------------------------------------|
| `API_THROTTLE_ANON` | `1000/day` | Rate limiting for anonymous (unauthenticated) users. |
| `API_THROTTLE_USER` | `10000/day` | Rate limiting for authenticated users. |
### LDAP Authentication
Enabling LDAP authentication is optional and disabled by default.
To enable LDAP, set the `AUTH_LDAP_SERVER_URI` value to the desired LDAP endpoint.
Application user fields can be mapped to LDAP attributes by specifying the `AUTH_LDAP_ATTR_MAP` setting.
The following example maps the `first_name` and `last_name` fields used by Keystone to the LDAP attributes `givenName` and `sn`:
```bash
AUTH_LDAP_ATTR_MAP="first_name=givenName,last_name=sn"
```
See the `apps.users.models.User` class for a full list of available Keystone fields.
| Setting Name | Default Value | Description |
|---------------------------|--------------------------|---------------------------------------------------------------|
| `AUTH_LDAP_SERVER_URI` | | The URI of the LDAP server. |
| `AUTH_LDAP_START_TLS` | `True` | Whether to use TLS when connecting to the LDAP server. |
| `AUTH_LDAP_BIND_DN` | | Optionally bind LDAP queries to the given DN. |
| `AUTH_LDAP_BIND_PASSWORD` | | The password to use when binding to the LDAP server. |
| `AUTH_LDAP_USER_SEARCH` | `(uid=%(user)s)` | The search query for finding a user in the LDAP server. |
| `AUTH_LDAP_REQUIRE_CERT` | `False` | Whether to require certificate verification. |
| `AUTH_LDAP_ATTR_MAP` | | A mapping of user fields to LDAP attribute names. |
### Database Connection
Official support is included for both SQLite and PostgreSQL database backends.
However, SQLite is intended for development and demonstrative use-cases only.
The PostgreSQL backend should always be used in production settings.
| Setting Name | Default Value | Description |
|---------------------------|--------------------------|---------------------------------------------------------------|
| `DB_POSTGRES_ENABLE` | `False` | Use PostgreSQL instead of the default Sqlite driver. |
| `DB_NAME` | `keystone` | The name of the application database. |
| `DB_USER` | | Username for database authentication (PostgreSQL only). |
| `DB_PASSWORD` | | Password for database authentication (PostgreSQL only). |
| `DB_HOST` | `localhost` | Database host address (PostgreSQL only). |
| `DB_PORT` | `5432` | Database host port (PostgreSQL only). |
### Redis Connection
Redis settings define the network location and connection information for the Redis backend.
Enabling password authentication is suggested when deploying Redis in a production environment.
| Setting Name | Default Value | Description |
|---------------------------|--------------------------|---------------------------------------------------------------|
| `REDIS_HOST` | `127.0.0.1` | URL for the Redis message cache. |
| `REDIS_PORT` | `6379` | Port number for the Redis message cache. |
| `REDIS_DB` | `0` | The Redis database number to use. |
| `REDIS_PASSWORD` | | Optionally connect using the given password. |
### Developer Settings
The following settings are intended exclusively for use in development.
The `DEBUG` option is inherently insecure and should **never** be enabled in production settings.
| Setting Name | Default Value | Description |
|---------------------------|--------------------------|---------------------------------------------------------------|
| `DEBUG` | `False` | Enable or disable debug mode. |
## Developer Notes
The following section details useful information for application contributors.
### Debug Mode
Running the application in debug mode enables/disables various features to aid in the development process.
In addition to enabling the standard debugging behavior provided by Django:
- A `/docs` page is enabled with full API documentation for the parent application
- Tracebacks are provided in the browser when an exception occurs (a Django standard)
### Admin Utilities
The `keystone-api` utility includes a series of admin utilities.
These utilities are useful for automating various development tasks.
A brief summary is provided below.
Use the `keystone-api <command> --help` option for specific usage information.
| Command | Description |
|---------------------------|------------------------------------------------------------------------------------------|
| `clean` | Clean up files generated when launching a new application instance. |
| `quickstart` | A helper utility for quickly migrating/deploying an application instance. |
### Tests and System Checks
Application tests are run using the `test` command:
```bash
keystone-api test
```
Specific subsets of tests are run by specifying an app label.
For example, tests for the `users` application are executed as:
```bash
keystone-api test apps.users
```
The default django system checks can also be executed as standard:
```bash
keystone-api check # Check for system configuration errors
keystone-api makemigrations --check # Check for missing database migrations
keystone-api health_check # Check the status of running backend services
```
### API Schema Generation
Use the `spectacular` command to dynamically generate an OpenAPI schema:
```bash
keystone-api spectacular >> api.yml
```
Raw data
{
"_id": null,
"home_page": null,
"name": "keystone-api",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.11",
"maintainer_email": null,
"keywords": "Pitt, CRC, HPC, django",
"author": "Daniel Perrefort",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/1a/4d/2a991ec970990042500f59dfff5698be48aaa09fd75db9280426a5a84539/keystone_api-0.3.11.tar.gz",
"platform": null,
"description": "# Keystone API\n\n[](https://app.codacy.com?utm_source=gh&utm_medium=referral&utm_content=&utm_campaign=Badge_grade)\n\nThe backend REST API for the Keystone allocation management dashboard.\n\n## Installation\n\nTo install the Keystone API, choose from one of the following options.\n\n### Using Docker\n\nUsing Docker is the recommended method for building and deploying application instances.\nThe most recent image can be pulled from the GitHub container registry:\n\n```bash\ndocker pull ghcr.io/pitt-crc/keystone-api\ndocker run -p 8000:8000 ghcr.io/pitt-crc/keystone-api\n```\n\nAlternatively, the latest development version can be built directly from source:\n\n```bash\ngit clone https://github.com/pitt-crc/keystone-api\ndocker build -t keystone-api:develop keystone-api\ndocker run -p 8000:8000 keystone-api:develop\n```\n\nThe container will automatically launch a fully functioning API server.\nIf the container is being launched for the first time, you will need to manually create the first user account.\nTo do so, execute the following command with the appropriate container name and follow the onscreen prompts.\n\n```bash\ndocker exec -it [CONTAINER NAME] keystone-api createsuperuser\n```\n\nThe default container instance is *not* suitable for full production out of the box.\nSee the [Settings](#settings) section for a complete overview of configurable options and recommended settings.\n\n### Installing from PyPI\n\nInstalling the Keystone-API Python package is only recommended as a fallback for situations where using Docker is not feasible.\nBefore proceeding with the installation, the following dependencies must be met:\n\n- A running Celery instance\n- A running Celery Beat instance\n- A running Redis database\n\nThe following dependencies are optional:\n\n- A running PostgreSQL database (if using PostgreSQL instead of SQLite)\n- LDAP development binaries (if using LDAP authentication)\n\nIn keeping with best practice, it is recommended to install packages into a dedicated virtual environment:\n\n```bash\nconda create -n keystone-api python=3.11\nconda activate keystone-api\n```\n\nThe package and its dependencies are pip installable.\n\n```bash\npip install keystone-api\n```\n\nIf the installation was successful, the packaged CLI tool will be available in your working environment.\nUse the `--help` option to view the available commands.\n\n```bash\nkeystone-api --help\n```\n\nThe following example will set up the project database, create an admin user account, and launch the\nAPI server in debug mode. As a general rule, debug mode should **never** be enabled in production.\n\n```bash\nkeystone-api migrate\nkeystone-api createsuperuser\nDEBUG=true keystone-api runserver\n```\n\n#### Enabling Autocomplete\n\nThe `keystone-api` utility does not support tab autocompletion by default.\nTo enable this feature, use the `enable_autocomplete` command:\n\n```bash\nkeystone-api enable_autocomplete\n```\n\n## Settings\n\nApplication settings are configurable as environmental variables.\nIndividual settings are listed below by category and use case.\n\n### Security\n\nImproperly configuring these settings can introduce dangerous vulnerabilities and may damage your production deployment.\nAdministrators should adhere to the following general guidelines:\n\n- Ensure your deployment is isolated behind a web proxy with proper HTTPS handling\n- Always define the `SECURE_ALLOWED_HOSTS` list using a restrictive collection of domain patterns\n- Avoid issuing session/CSRF tokens over unsecured connections by enabling `SECURE_SESSION_TOKENS`\n- Always use a secure `SECURE_SECRET_KEY` value to ensure proper request signing across application instances/restarts\n- Consider using HTTP Strict Transport Security (HSTS) to enforce the use of HTTPS\n\nThe `SECURE_SECRET_KEY` value may be changed at any given time. However, doing so may invalidate any active user\nsessions and require users to reauthenticate.\n\n| Setting Name | Default Value | Description |\n|---------------------------------|-----------------------|---------------------------------------------------------|\n| `SECURE_SECRET_KEY` | Randomly generated | Secret key used to enforce cryptographic signing. |\n| `SECURE_ALLOWED_HOSTS` | `localhost,127.0.0.1` | Comma-separated list of accepted host/domain names. |\n| `SECURE_SSL_REDIRECT` | `False` | Automatically redirect all HTTP traffic to HTTPS. |\n| `SECURE_SESSION_TOKENS` | `False` | Only issue session/CSRF tokens over secure connections. |\n| `SECURE_CSRF_ORIGINS` | `[]` | Domains (with protocol) to accept CSRF headers from. |\n| `SECURE_HSTS_SECONDS` | `0` (Disabled) | HSTS cache duration in seconds. |\n| `SECURE_HSTS_SUBDOMAINS` | `False` | Enable HSTS for subdomains. |\n| `SECURE_HSTS_PRELOAD` | `False` | Enable HSTS preload functionality. |\n| `SECURE_ACCESS_TOKEN_LIFETIME` | `300` (5 Minutes) | JWT Access token lifetime in seconds. |\n| `SECURE_REFRESH_TOKEN_LIFETIME` | `86400` (1 Day) | JWT Refresh token lifetime in seconds. |\n\n\n### General Configuration\n\nThe following settings configure varius aspects of Keystone's backend behavior.\n\nKeystone uses various static files to facilitate operation and support user requests.\nBy default, these files are stored in subdirectories of the installed application directory (`<app>`).\n\n| Setting Name | Default Value | Description |\n|---------------------------|---------------------------|---------------------------------------------------------------------------------------------------|\n| `CONFIG_TIMEZONE` | `UTC` | The application timezone. |\n| `CONFIG_STATIC_DIR` | `<app>/static_files` | Where to store internal static files required by the application. |\n| `CONFIG_UPLOAD_DIR` | `<app>/upload_files` | Where to store file data uploaded by users. |\n| `CONFIG_LOG_RETENTION` | 30 days | How long to store log records in seconds. Set to 0 to keep all records. |\n| `CONFIG_LOG_LEVEL` | `WARNING` | Only record logs above this level (`CRITICAL`, `ERROR`, `WARNING`, `INFO`, `DEBUG`, or `NOTSET`). |\n\n### API Throttling\n\nAPI settings are used to throttle incoming API requests against a maximum limit.\nLimits are specified as the maximum number of requests per `day`, `minute`, `hour`, or `second`.\n\n| Setting Name | Default Value | Description |\n|---------------------------|--------------------------|---------------------------------------------------------------|\n| `API_THROTTLE_ANON` | `1000/day` | Rate limiting for anonymous (unauthenticated) users. |\n| `API_THROTTLE_USER` | `10000/day` | Rate limiting for authenticated users. |\n\n### LDAP Authentication\n\nEnabling LDAP authentication is optional and disabled by default.\nTo enable LDAP, set the `AUTH_LDAP_SERVER_URI` value to the desired LDAP endpoint.\n\nApplication user fields can be mapped to LDAP attributes by specifying the `AUTH_LDAP_ATTR_MAP` setting.\nThe following example maps the `first_name` and `last_name` fields used by Keystone to the LDAP attributes `givenName` and `sn`:\n\n```bash\nAUTH_LDAP_ATTR_MAP=\"first_name=givenName,last_name=sn\"\n```\n\nSee the `apps.users.models.User` class for a full list of available Keystone fields.\n\n| Setting Name | Default Value | Description |\n|---------------------------|--------------------------|---------------------------------------------------------------|\n| `AUTH_LDAP_SERVER_URI` | | The URI of the LDAP server. |\n| `AUTH_LDAP_START_TLS` | `True` | Whether to use TLS when connecting to the LDAP server. |\n| `AUTH_LDAP_BIND_DN` | | Optionally bind LDAP queries to the given DN. |\n| `AUTH_LDAP_BIND_PASSWORD` | | The password to use when binding to the LDAP server. |\n| `AUTH_LDAP_USER_SEARCH` | `(uid=%(user)s)` | The search query for finding a user in the LDAP server. |\n| `AUTH_LDAP_REQUIRE_CERT` | `False` | Whether to require certificate verification. |\n| `AUTH_LDAP_ATTR_MAP` | | A mapping of user fields to LDAP attribute names. |\n\n### Database Connection\n\nOfficial support is included for both SQLite and PostgreSQL database backends.\nHowever, SQLite is intended for development and demonstrative use-cases only.\nThe PostgreSQL backend should always be used in production settings.\n\n| Setting Name | Default Value | Description |\n|---------------------------|--------------------------|---------------------------------------------------------------|\n| `DB_POSTGRES_ENABLE` | `False` | Use PostgreSQL instead of the default Sqlite driver. |\n| `DB_NAME` | `keystone` | The name of the application database. |\n| `DB_USER` | | Username for database authentication (PostgreSQL only). |\n| `DB_PASSWORD` | | Password for database authentication (PostgreSQL only). |\n| `DB_HOST` | `localhost` | Database host address (PostgreSQL only). |\n| `DB_PORT` | `5432` | Database host port (PostgreSQL only). |\n\n### Redis Connection\n\nRedis settings define the network location and connection information for the Redis backend.\nEnabling password authentication is suggested when deploying Redis in a production environment.\n\n| Setting Name | Default Value | Description |\n|---------------------------|--------------------------|---------------------------------------------------------------|\n| `REDIS_HOST` | `127.0.0.1` | URL for the Redis message cache. |\n| `REDIS_PORT` | `6379` | Port number for the Redis message cache. |\n| `REDIS_DB` | `0` | The Redis database number to use. |\n| `REDIS_PASSWORD` | | Optionally connect using the given password. |\n\n### Developer Settings\n\nThe following settings are intended exclusively for use in development.\nThe `DEBUG` option is inherently insecure and should **never** be enabled in production settings.\n\n| Setting Name | Default Value | Description |\n|---------------------------|--------------------------|---------------------------------------------------------------|\n| `DEBUG` | `False` | Enable or disable debug mode. |\n\n## Developer Notes\n\nThe following section details useful information for application contributors.\n\n### Debug Mode\n\nRunning the application in debug mode enables/disables various features to aid in the development process.\nIn addition to enabling the standard debugging behavior provided by Django:\n\n- A `/docs` page is enabled with full API documentation for the parent application\n- Tracebacks are provided in the browser when an exception occurs (a Django standard)\n\n### Admin Utilities\n\nThe `keystone-api` utility includes a series of admin utilities.\nThese utilities are useful for automating various development tasks.\nA brief summary is provided below.\nUse the `keystone-api <command> --help` option for specific usage information.\n\n| Command | Description |\n|---------------------------|------------------------------------------------------------------------------------------|\n| `clean` | Clean up files generated when launching a new application instance. |\n| `quickstart` | A helper utility for quickly migrating/deploying an application instance. |\n\n### Tests and System Checks\n\nApplication tests are run using the `test` command:\n\n```bash\nkeystone-api test\n```\n\nSpecific subsets of tests are run by specifying an app label.\nFor example, tests for the `users` application are executed as:\n\n```bash\nkeystone-api test apps.users\n```\n\nThe default django system checks can also be executed as standard:\n\n```bash\nkeystone-api check # Check for system configuration errors\nkeystone-api makemigrations --check # Check for missing database migrations\nkeystone-api health_check # Check the status of running backend services\n```\n\n### API Schema Generation\n\nUse the `spectacular` command to dynamically generate an OpenAPI schema:\n\n```bash\nkeystone-api spectacular >> api.yml\n```\n\n",
"bugtrack_url": null,
"license": null,
"summary": "A REST API for managing user resource allocations on HPC systems.",
"version": "0.3.11",
"project_urls": null,
"split_keywords": [
"pitt",
" crc",
" hpc",
" django"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "49980c3dc3181bc6b76fd515b526c15768682e10706236285e96429da951ec5a",
"md5": "66f3cc025ec7803044c33da7d97363b3",
"sha256": "f517dd47009e3d8c83640200756ed665be0f94118604c3fb829f37652e72c555"
},
"downloads": -1,
"filename": "keystone_api-0.3.11-py3-none-any.whl",
"has_sig": false,
"md5_digest": "66f3cc025ec7803044c33da7d97363b3",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.11",
"size": 99859,
"upload_time": "2024-05-15T19:48:16",
"upload_time_iso_8601": "2024-05-15T19:48:16.019990Z",
"url": "https://files.pythonhosted.org/packages/49/98/0c3dc3181bc6b76fd515b526c15768682e10706236285e96429da951ec5a/keystone_api-0.3.11-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "1a4d2a991ec970990042500f59dfff5698be48aaa09fd75db9280426a5a84539",
"md5": "3efddcea471e34c827e5f738158b4d21",
"sha256": "d32c1a6e687bd5294964d4a29fbe4ea4e2292da63ac4f0e9750bbfb9a33db856"
},
"downloads": -1,
"filename": "keystone_api-0.3.11.tar.gz",
"has_sig": false,
"md5_digest": "3efddcea471e34c827e5f738158b4d21",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.11",
"size": 51659,
"upload_time": "2024-05-15T19:48:17",
"upload_time_iso_8601": "2024-05-15T19:48:17.831685Z",
"url": "https://files.pythonhosted.org/packages/1a/4d/2a991ec970990042500f59dfff5698be48aaa09fd75db9280426a5a84539/keystone_api-0.3.11.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-05-15 19:48:17",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "keystone-api"
}
