{"id":29687287,"url":"https://github.com/thepalaceproject/virtual-library-card","last_synced_at":"2026-05-20T20:13:14.048Z","repository":{"id":221738870,"uuid":"755245571","full_name":"ThePalaceProject/virtual-library-card","owner":"ThePalaceProject","description":"Virtual Library Card Creator ","archived":false,"fork":false,"pushed_at":"2025-06-18T19:28:24.000Z","size":2984,"stargazers_count":1,"open_issues_count":0,"forks_count":1,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-06-18T20:21:23.605Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":false,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ThePalaceProject.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"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":"2024-02-09T18:19:45.000Z","updated_at":"2025-06-18T19:26:04.000Z","dependencies_parsed_at":"2024-06-18T19:33:50.989Z","dependency_job_id":"7289762f-5643-458e-9cb3-1388354fe104","html_url":"https://github.com/ThePalaceProject/virtual-library-card","commit_stats":null,"previous_names":["thepalaceproject/virtual-library-card"],"tags_count":15,"template":false,"template_full_name":null,"purl":"pkg:github/ThePalaceProject/virtual-library-card","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ThePalaceProject%2Fvirtual-library-card","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ThePalaceProject%2Fvirtual-library-card/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ThePalaceProject%2Fvirtual-library-card/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ThePalaceProject%2Fvirtual-library-card/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ThePalaceProject","download_url":"https://codeload.github.com/ThePalaceProject/virtual-library-card/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ThePalaceProject%2Fvirtual-library-card/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":266619012,"owners_count":23957273,"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-23T02:00:09.312Z","response_time":66,"last_error":null,"robots_txt_status":null,"robots_txt_updated_at":null,"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":"2025-07-23T04:36:35.698Z","updated_at":"2026-05-20T20:13:04.036Z","avatar_url":"https://github.com/ThePalaceProject.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Virtual Library Card\n\n[![Test](https://github.com/ThePalaceProject/virtual-library-card/actions/workflows/test.yml/badge.svg)](https://github.com/ThePalaceProject/virtual-library-card/actions/workflows/test.yml)\n[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)\n[![Imports: isort](https://img.shields.io/badge/%20imports-isort-%231674b1?style=flat\u0026labelColor=ef8336)](https://pycqa.github.io/isort/)\n[![pre-commit](https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit\u0026logoColor=white)](https://github.com/pre-commit/pre-commit)\n![Python: 3.10,3.11,3.12](https://img.shields.io/badge/Python-3.10%20|%203.11%20|%203.12-blue)\n\n## Prerequisites\n\nPython 3.10+ must be installed, and a SQL database must be available.\n\n## Notes\n\n- The project settings are split into 2 files inside the \"settings\" directory. \"base.py\" contains the common\n  definitions, while \"dev.py\" contains an example configuration for development.\n- The website and API are in the same Django project and app. The `HAS_API` and `HAS_WEBSITE` flags allow\n  control over what is deployed.\n\n## Running the application locally\n\n### 1. Clone the repository\n\n    git clone git@github.com:ThePalaceProject/virtual-library-card.git\n\n### 2. Create and initialize a Python virtual env\n\n    pip install --upgrade pip\n    pip install virtualenv\n    python3 -m venv venv\n    source venv/bin/activate\n    poetry install --only-root\n\nNote: activate the virtual env before installing the requirements.\n\n### 3. Set up public MinIO bucket (or public AWS S3 bucket)\n\nVLC puts static files into public AWS S3 bucket so to run the VLC locally the easiest will be to run the MinIO locally in\na Docker container. You can read more about MinIO [here](https://min.io/docs/minio/container/index.html).\n\nTo run the MinIO in Docker container run:\n\n    docker run -d -p 9000:9000 -p 9001:9001 --name minio \\\n      -e \"MINIO_ROOT_USER=vlc-minio\" -e \"MINIO_ROOT_PASSWORD=123456789\" \\\n      quay.io/minio/minio server /data --console-address \":9001\"\n\nAfter you have MinIO container running, you will need to create the public bucket to put the static files in.\nLog into `http://localhost:9001` with username `vlc-minio` and password `123456789`.\nCreate bucket named `vlc-test` and make it public. The name for the bucket can be changed inside the settings file by\nmeans of the variable `AWS_STORAGE_BUCKET_NAME`.\n\n### 4. Collect the static files\n\nThe static files must be \"collected\":\n\n    python ./manage.py collectstatic --settings=virtual_library_card.settings.dev\n\nOur default configuration puts these files into a public s3 bucket.\n\nSee [django documentation](https://docs.djangoproject.com/en/2.2/howto/deployment/wsgi/modwsgi/#serving-files).\n\n### 5. Create a database and adjust the database connection parameters`\n\nThe database connection parameters for a development (resp. production) environment are located in the `settings/dev.py`\n(resp.`settings/prod.py`) files:\n\n    DATABASES = {\n        'default': {\n            'ENGINE': 'django.db.backends.postgresql',\n            'NAME': 'virtual_library_card',\n            'USER': '\u003cdb_user\u003e',\n            'PASSWORD': '\u003cdb_password\u003e',\n            'HOST': '\u003cdb_host\u003e',\n            'PORT': '\u003cdb_port\u003e',\n        }\n    }\n\n### 6. Create / update the database schema\n\nThe database schema must be initialized and updated with:\n\n    python3 manage.py migrate --settings=virtual_library_card.settings.dev\n\n### 7. Create the superuser\n\n    python manage.py createsuperuser --settings=virtual_library_card.settings.dev\n\nNotes:\n\n- This will also create the \"default\" library, which can be customized through a few settings in `settings/dev.py`:\n\n        DEFAULT_SUPERUSER_LIBRARY_NAME\n        DEFAULT_SUPERUSER_LIBRARY_IDENTIFIER\n        DEFAULT_SUPERUSER_LIBRARY_PREFIX\n        DEFAULT_SUPERUSER_LIBRARY_STATE\n\n- The name of the superuser can be also configured in the settings files:\n\n        DEFAULT_SUPERUSER_FIRST_NAME\n\n### 8. Select what (website or/and API) will be deployed\n\nThe website and API are in the same Django project and app. The `HAS_API` and `HAS_WEBSITE` flags allow to control\nwhat is deployed.\nYou can adjust these values in the `settings/dev.py` file.\n\n### 9. Run webserver\n\n#### Development\n\nFor development, you can use the Django `runserver` command.\n\n    python manage.py runserver --settings=virtual_library_card.settings.dev\n\n#### UWSGI\n\nFor development or production use you can run the application under uwsgi.\n\n    uwsgi --wsgi-file virtual_library_card/wsgi.py --http :8000\n\n## Running the application with docker-compose\n\nWe have an example [docker-compose.yml](docker-compose.yml) that can be used as a starting\npoint for deploying the code to production, or as an easy way to run the application for\ndevelopment. It runs three containers: postgresql, minio and vlc. It takes care of setting\nup the environment variables to configure the containers to talk to one another.\n\n    docker-compose up -d\n\nThen you should be able to access the site at `http://localhost:8000` with the username (test@test.com)\nand password (test) defined in [`docker-compose.yml`](./docker-compose.yml).\n\n## Running the application in docker\n\n### 1. Build docker container\n\nAfter cloning the repository, this step builds the docker container.\nEventually you will be able to pull the container from dockerhub.\n\n    docker build -t virtual_libary_card .\n\n### 2. Create PostgreSQL Container (Only for testing)\n\nEither create a new database in the production PostgreSQL Database. Or use the docker PostgreSQL container for testing.\n\n    docker run -d --name pg --rm -e POSTGRES_USER=vlc -e POSTGRES_PASSWORD=test -e POSTGRES_DB=virtual_library_card postgres:16\n\n### 3. Create settings file\n\nCreate the settings file for the app and bind mount it into the container. The `virtual_library_card/settings/dev.py`\nis an example of this file, and in most cases can be used for basic testing.\n\n### 4. Start container\n\n    docker run --name vlc --rm -p 8000:8000 -e SUPERUSER_EMAIL=test@test.com -e SUPERUSER_PASSWORD=test -e \\\n      DJANGO_SETTINGS_MODULE=virtual_library_card.settings.dev --link pg virtual_library_card\n\n### 5. View site\n\nThe site should be available in your browser for testing at `https://localhost:8000`.\n\n## Other settings\n\nThe `RECAPTCHA_PUBLIC_KEY` and `RECAPTCHA_PRIVATE_KEY` must be set if the `django_recaptcha` django plugin\nis installed via the `INSTALLED_APPS` setting.\nIf the `django_recaptcha` App is not in the `INSTALLED_APPS` setting, the signup flow will silently remove the need for\ncaptcha to be present on that page.\n\n### Environment Variables\n\n**DJANGO_LOG_LEVEL**: Can be a python log level string. It defaults to `INFO`.\nAll application logging occurs at this defined level.\n\n### AWS S3 Setup\n\nAn S3 bucket should be created out-of-band to store uploaded files and static files.\nThe following variables must be populated in the settings file.\n\n    `DEFAULT_FILE_STORAGE` = \"virtual_library_card.storage.S3PublicStorage\"\n    `STATICFILES_STORAGE` = \"virtual_library_card.storage.S3StaticStorage\"\n    `AWS_STORAGE_BUCKET_NAME` = \"The name of the already created S3 bucket\"\n\nOptionally, the following settings can be set\n\n    # Either\n    `AWS_S3_SESSION_PROFILE` = \"profile-name\"\n    # Or\n    `AWS_S3_ACCESS_KEY_ID` = \"The AWS access key\"\n    `AWS_S3_SECRET_ACCESS_KEY` = \"The AWS secret key\"\n\nIn case neither session profile or key-secret are provided, the boto3 \"default\" session will be used.\n\nAdditional optional settings can be added as per the documentation for\n[django-storages](https://django-storages.readthedocs.io/en/latest/).\nIn a development setting the minio container may also be used to mimic\na local S3 deployment, in which case `AWS_S3_ENDPOINT_URL` should also be configured.\nRefer [Bitnami Minio](https://hub.docker.com/r/bitnami/minio/).\n\n## Testing \u0026 CI\n\nThis project runs all the unit tests through Github Actions for new pull requests and when merging into the default\n`main` branch. The relevant file can be found in `.github/workflows/test.yml`. When contributing updates or fixes,\nit's required for the test Github Action to pass for all python environments.\n\n### Code Style\n\nCode style on this project is linted using [pre-commit](https://pre-commit.com/). This python application is included\nin our `pyproject.toml` file, so if you have the applications requirements installed it should be available. pre-commit\nis run automatically on each push and PR.\n\nYou can run it manually on all files with the command: `pre-commit run --all-files`.\n\nFor more details about our code style, see the\n[code style section of the circulation README](https://github.com/ThePalaceProject/circulation#code-style).\n\n### Testing\n\nGithub Actions runs our unit tests against different Python versions automatically using\n[tox](https://tox.readthedocs.io/en/latest/). `tox` is included in our development dependencies, so it should be\navailable once you run `poetry install`.\n\nTox has an environment for each python version and an optional `-docker` factor that will automatically use docker to\ndeploy service container used for the tests. You can select the environment you would like to test with the tox `-e`\nflag.\n\n#### Environments\n\n| Environment | Python Version |\n|-------------|----------------|\n| py310       | Python 3.10    |\n| py311       | Python 3.11    |\n| py312       | Python 3.12    |\n\nAll of these environments are tested by default when running tox. To test one specific environment you can use the `-e`\nflag.\n\nTest Python 3.10\n\n    tox -e py310\n\nYou need to have the Python versions you are testing against installed on your local system. `tox` searches the system\nfor installed Python versions, but does not install new Python versions. If `tox` doesn't find the Python version its\nlooking for it will give an `InterpreterNotFound` error.\n\n[Pyenv](https://github.com/pyenv/pyenv) is a useful tool to install multiple Python versions, if you need to install\nmissing Python versions in your system for local testing.\n\n#### Docker\n\nIf you install `tox-docker` tox will take care of setting up all the service containers necessary to run the unit tests\nand pass the correct environment variables to configure the tests to use these services. Using `tox-docker` is not\nrequired, but it is the recommended way to run the tests locally, since it runs the tests in the same way they are run\non Github Actions. `tox-docker` is included in the project's development dependencies, so it should always be available.\n\nThe docker functionality is included in a `docker` factor that can be added to the environment. To run an environment\nwith a particular factor you add it to the end of the environment.\n\nTest with Python 3.10 using docker containers for the services.\n\n    tox -e py310-docker\n\n#### Pytest\n\nTests are performed using [pytest-django](https://pytest-django.readthedocs.io/en/latest/index.html). The tests\nrequire a database, and use the settings configured in [dev.py](virtual_library_card/settings/dev.py). The test database\nuses the database name configured in `dev.py` with `test_` prepended to it (`test_virtual_library_card_dev`). This\ndatabase will be created automatically by the tests, and cleaned up afterwords. So the database user must have\npermission to create and drop databases.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthepalaceproject%2Fvirtual-library-card","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fthepalaceproject%2Fvirtual-library-card","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthepalaceproject%2Fvirtual-library-card/lists"}