From 1344adc37df390ec7d643e170fe0dc8b847df5f5 Mon Sep 17 00:00:00 2001 From: Kumi Date: Thu, 14 Mar 2024 18:14:25 +0100 Subject: [PATCH] Added LICENSE and enhanced project documentation Introduced an MIT LICENSE file for open sourcing the project, ensuring that users are aware of their rights to use, modify, and distribute the software. This change underlines our commitment to the open source community and clarifies usage terms. Updated the README.md with detailed development setup instructions, making it easier for new contributors to get started with the project. The amendments include steps from cloning the repository to starting the development server, highlighting mandatory installations and configurations for a smooth setup. Adjusted settings.py and settings.dist.ini for better clarity and customization. Simplifications in settings.py improve code readability and maintainability. The addition of settings.dist.ini allows users to easily configure their development and production environments per their needs without altering core configuration files. These enhancements aim to simplify the contribution process, foster community involvement, and ensure a transparent and flexible setup for developers engaging with the project. --- LICENSE | 19 ++++++++++ README.md | 79 +++++++++++++++++++++++++++++++++++++++++- quackscape/settings.py | 53 ++++++++++++++-------------- settings.dist.ini | 24 +++++++++++++ 4 files changed, 147 insertions(+), 28 deletions(-) create mode 100644 LICENSE create mode 100644 settings.dist.ini diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..2cab9cb --- /dev/null +++ b/LICENSE @@ -0,0 +1,19 @@ +Copyright (c) 2023 Private.coffee Team + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/README.md b/README.md index cabab8c..2a37862 100644 --- a/README.md +++ b/README.md @@ -6,7 +6,84 @@ Quackscape is a content management system for panoramic/VR photos and videos. It - Python 3.8+ - Redis -- ffmpeg - NodeJS / NPM +- ffmpeg (for video processing) - MariaDB or MySQL (optional but recommended) - A web server (Caddy, gunicorn, Nginx, Apache, etc.) (optional but recommended) + +## Development Setup + +1. Clone the repository + +2. Create a virtual environment and install the requirements + +```bash +python3 -m venv venv +source venv/bin/activate +pip install -r requirements.txt +``` + +3. Install the frontend dependencies + +```bash +npm install +``` + +4. Copy `settings.dist.ini` to `settings.ini` and fill in the required settings + +5. Run the migrations + +```bash +python manage.py migrate +``` + +6. Compile the frontend assets + +```bash +npm run build:dev +``` + +If you are working on the frontend, you can instead use the `npm run watch:dev` command to automatically recompile the frontend assets when they change. + +7. Run the development server + +```bash +python manage.py rundev +``` + +8. Create a superuser + +```bash +python manage.py createsuperuser +``` + +9. Visit `http://localhost:8000` in your web browser + +## Production Setup + +As this is still quite a ways from a stable project, we do not include production setup steps here. Very fundamentally, the production setup would be similar to the development setup. However, there are a few differences: + +- Instead of `npm run build:dev`, you should run `npm run build`. +- You should make sure to configure a database such as MariaDB or MySQL. You should not use the default SQLite database in production. +- Instead of `python manage.py runserver`, you should use a production-ready web server such as Caddy and gunicorn. +- Instead of `python manage.py runserver`, you will want to use the `python manage.py runworker` command to start the background worker process. +- You may want to use systemd or another process manager to keep the server and worker processes running in the background. + +## Workers + +Quackscape uses a background worker to process uploaded photos and videos. You can start the worker process using the `python manage.py runworker` command. + +You may want to run the worker process on another machine. The server part is not very resource-hungry, so it can easily run on a VPS, but for video processing, you may want to use a machine with more resources, ideally with a powerful GPU. + +To run the worker process on another machine, you first follow the basic setup instructions on that machine as well, then add a line like this to the worker's `settings.ini`: + +```ini +[Quackscape] +Redis = redis://:6379/0 +``` + +Replace `` with the IP address of the machine running the Redis server. This way, the worker will be able to fetch tasks from the same Redis server the Quackscape server is writing them to. + +## License + +This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details. diff --git a/quackscape/settings.py b/quackscape/settings.py index ebd37d0..2875966 100644 --- a/quackscape/settings.py +++ b/quackscape/settings.py @@ -10,9 +10,7 @@ ASK = AutoSecretKey("settings.ini") SECRET_KEY = ASK.secret_key -DEBUG = ASK.config.getboolean( - "Quackscape", "Debug", fallback=False -) +DEBUG = ASK.config.getboolean("Quackscape", "Debug", fallback=False) ALLOWED_HOSTS = [ host.strip() @@ -22,7 +20,7 @@ ALLOWED_HOSTS = [ CSRF_TRUSTED_ORIGINS = [f"https://{host}" for host in ALLOWED_HOSTS] USE_X_FORWARDED_HOST = True -SECURE_PROXY_SSL_HEADER = ('HTTP_X_FORWARDED_PROTO', 'https') +SECURE_PROXY_SSL_HEADER = ("HTTP_X_FORWARDED_PROTO", "https") # Application definition @@ -37,8 +35,8 @@ INSTALLED_APPS = [ "rest_framework", "django_celery_beat", "django_celery_results", - 'drf_spectacular', - 'drf_spectacular_sidecar', + "drf_spectacular", + "drf_spectacular_sidecar", "quackscape", "quackscape.users", "quackscape.tours", @@ -90,7 +88,7 @@ if (dbtype := "MySQL") in ASK.config or (dbtype := "MariaDB") in ASK.config: } } -elif (dbtype := "Postgres") in ASK.config or (dbtype:= "PostgreSQL") in ASK.config: +elif (dbtype := "Postgres") in ASK.config or (dbtype := "PostgreSQL") in ASK.config: DATABASES = { "default": { "ENGINE": "django.db.backends.postgresql", @@ -111,7 +109,6 @@ else: } - # Password validation # https://docs.djangoproject.com/en/5.0/ref/settings/#auth-password-validators @@ -185,20 +182,22 @@ DEFAULT_AUTO_FIELD = "django.db.models.BigAutoField" # Django Rest Framework settings SPECTACULAR_SETTINGS = { - 'SWAGGER_UI_DIST': 'SIDECAR', - 'SWAGGER_UI_FAVICON_HREF': 'SIDECAR', - 'REDOC_DIST': 'SIDECAR', + "SWAGGER_UI_DIST": "SIDECAR", + "SWAGGER_UI_FAVICON_HREF": "SIDECAR", + "REDOC_DIST": "SIDECAR", } REST_FRAMEWORK = { - 'DEFAULT_SCHEMA_CLASS': 'drf_spectacular.openapi.AutoSchema', + "DEFAULT_SCHEMA_CLASS": "drf_spectacular.openapi.AutoSchema", } # Celery settings -CELERY_BROKER_URL = 'redis://localhost:6379/0' -CELERY_RESULT_BACKEND = 'django-db' +CELERY_BROKER_URL = ASK.config.get( + "Quackscape", "Redis", fallback="redis://localhost:6379/0" +) +CELERY_RESULT_BACKEND = "django-db" # Quackscape settings @@ -214,26 +213,26 @@ QUACKSCAPE_CONTENT_RESOLUTIONS = [ (8192, 4096), (16384, 8192), (32768, 16384), - (65536, 32768) + (65536, 32768), ] # ffmpeg settings FFMPEG_OPTIONS = { - 'default': { - 'global_options': '-hide_banner -y', - 'input_options': '', - 'output_options': '-c:v libx264 -preset veryfast -crf 23 -c:a aac -b:a 128k', + "default": { + "global_options": "-hide_banner -y", + "input_options": "", + "output_options": "-c:v libx264 -preset veryfast -crf 23 -c:a aac -b:a 128k", }, - 'high_quality': { - 'global_options': '-hide_banner -y', - 'input_options': '', - 'output_options': '-c:v libx264 -preset slow -crf 18 -c:a aac -b:a 320k', + "high_quality": { + "global_options": "-hide_banner -y", + "input_options": "", + "output_options": "-c:v libx264 -preset slow -crf 18 -c:a aac -b:a 320k", }, - 'nvidia': { - 'global_options': '-hide_banner -y', - 'input_options': '', - 'output_options': '-c:v h264_nvenc -preset slow -cq:v 18 -c:a aac -b:a 320k', + "nvidia": { + "global_options": "-hide_banner -y", + "input_options": "", + "output_options": "-c:v h264_nvenc -preset slow -cq:v 18 -c:a aac -b:a 320k", }, } diff --git a/settings.dist.ini b/settings.dist.ini new file mode 100644 index 0000000..8f5985b --- /dev/null +++ b/settings.dist.ini @@ -0,0 +1,24 @@ +[Quackscape] +Debug = 1 # Set to 0 for production +Host = quackscape.local # Set to the domain name of the server +#Redis = redis://localhost:6379/0 # Uncomment to change the default Redis connection + +# Uncomment if you want to use the nvidia hardware acceleration for ffmpeg: +#[ffmpeg] +#DefaultOption = nvidia + +# Uncomment if you want to use MinIO or another S3 compatible storage: +#[S3] +#Bucket = quackscape +#AccessKey = quackscape +#SecretKey = secret! +#Endpoint = https://minio.local +#LocalStatic = 1 # Uncomment if you want to serve static files from the local server instead of S3 + +# Uncomment to set up a database connection. Only one of the headers should be uncommented: +#[Postgres] +#[MySQL] +#Host = localhost +#Username = quackscape +#Password = secret! +#Database = quackscape