diff --git a/.github/actions/setup/action.yaml b/.github/actions/setup/action.yaml index 86aa699b38..d43fa57e71 100644 --- a/.github/actions/setup/action.yaml +++ b/.github/actions/setup/action.yaml @@ -86,8 +86,8 @@ runs: - name: Run invoke install if: ${{ inputs.install == 'true' }} shell: bash - run: invoke install + run: invoke install --uv - name: Run invoke update if: ${{ inputs.update == 'true' }} shell: bash - run: invoke update + run: invoke update --uv diff --git a/.github/workflows/qc_checks.yaml b/.github/workflows/qc_checks.yaml index 50d0b0fa90..db11adc07f 100644 --- a/.github/workflows/qc_checks.yaml +++ b/.github/workflows/qc_checks.yaml @@ -111,9 +111,12 @@ jobs: pip install -r docs/requirements.txt python docs/ci/check_mkdocs_config.py - name: Check Links - run: | - pip install linkcheckmd requests - python -m linkcheckmd docs --recurse + uses: gaurav-nelson/github-action-markdown-link-check@v1 + with: + folder-path: docs + config-file: docs/mlc_config.json + check-modified-files-only: 'yes' + use-quiet-mode: 'yes' schema: name: Tests - API Schema Documentation diff --git a/Dockerfile b/Dockerfile index a17537c672..1208960886 100644 --- a/Dockerfile +++ b/Dockerfile @@ -62,7 +62,9 @@ RUN apk add --no-cache \ # Image format support libjpeg libwebp zlib \ # Weasyprint requirements : https://doc.courtbouillon.org/weasyprint/stable/first_steps.html#alpine-3-12 - py3-pip py3-pillow py3-cffi py3-brotli pango poppler-utils openldap && \ + py3-pip py3-pillow py3-cffi py3-brotli pango poppler-utils openldap \ + # Core database packages + postgresql13-client && \ # fonts apk --update --upgrade --no-cache add fontconfig ttf-freefont font-noto terminus-font && fc-cache -f diff --git a/InvenTree/InvenTree/settings.py b/InvenTree/InvenTree/settings.py index e240b50283..4d2b85e311 100644 --- a/InvenTree/InvenTree/settings.py +++ b/InvenTree/InvenTree/settings.py @@ -136,6 +136,11 @@ STATICFILES_DIRS = [] STATICFILES_I18_PREFIX = 'i18n' STATICFILES_I18_SRC = BASE_DIR.joinpath('templates', 'js', 'translated') STATICFILES_I18_TRG = BASE_DIR.joinpath('InvenTree', 'static_i18n') + +# Create the target directory if it does not exist +if not STATICFILES_I18_TRG.exists(): + STATICFILES_I18_TRG.mkdir(parents=True) + STATICFILES_DIRS.append(STATICFILES_I18_TRG) STATICFILES_I18_TRG = STATICFILES_I18_TRG.joinpath(STATICFILES_I18_PREFIX) diff --git a/InvenTree/config_template.yaml b/InvenTree/config_template.yaml index 0b4f753670..931c135d1e 100644 --- a/InvenTree/config_template.yaml +++ b/InvenTree/config_template.yaml @@ -215,7 +215,7 @@ login_default_protocol: http # Remote / proxy login # These settings can introduce security problems if configured incorrectly. Please read -# https://docs.djangoproject.com/en/4.0/howto/auth-remote-user/ for more details +# https://docs.djangoproject.com/en/4.2/howto/auth-remote-user/ for more details # The header name should be prefixed by `HTTP`. Please read the docs for more details # https://docs.djangoproject.com/en/stable/ref/request-response/#django.http.HttpRequest.META remote_login_enabled: False diff --git a/docker/production/.env b/docker/.env similarity index 53% rename from docker/production/.env rename to docker/.env index 75f7486037..39ac250ccb 100644 --- a/docker/production/.env +++ b/docker/.env @@ -1,16 +1,8 @@ -# InvenTree environment variables for a postgresql production setup +# InvenTree environment variables for docker compose deployment -# Location of persistent database data (stored external to the docker containers) -# Note: You *must* un-comment this line, and point it to a path on your local machine - -# e.g. Linux -#INVENTREE_EXT_VOLUME=/home/inventree/data - -# e.g. Windows (docker desktop) -#INVENTREE_EXT_VOLUME=c:/Users/inventree/data - -# Default web port for the InvenTree server -INVENTREE_WEB_PORT=1337 +# Specify the location of the external data volume +# By default, placed in local directory 'inventree-data' +INVENTREE_EXT_VOLUME=./inventree-data # Ensure debug is false for a production setup INVENTREE_DEBUG=False @@ -23,16 +15,14 @@ INVENTREE_LOG_LEVEL=WARNING #INVENTREE_ADMIN_EMAIL= # Database configuration options -# Note: The example setup is for a PostgreSQL database INVENTREE_DB_ENGINE=postgresql INVENTREE_DB_NAME=inventree INVENTREE_DB_HOST=inventree-db INVENTREE_DB_PORT=5432 -# Database credentials - These must be configured before running -# Uncomment the lines below, and change from the default values! -#INVENTREE_DB_USER=pguser -#INVENTREE_DB_PASSWORD=pgpassword +# Database credentials - These should be changed from the default values! +INVENTREE_DB_USER=pguser +INVENTREE_DB_PASSWORD=pgpassword # Redis cache setup (disabled by default) # Un-comment the following lines to enable Redis cache @@ -45,12 +35,15 @@ INVENTREE_DB_PORT=5432 INVENTREE_GUNICORN_TIMEOUT=90 # Enable custom plugins? -INVENTREE_PLUGINS_ENABLED=False +INVENTREE_PLUGINS_ENABLED=True # Run migrations automatically? -INVENTREE_AUTO_UPDATE=False +INVENTREE_AUTO_UPDATE=True # Image tag that should be used INVENTREE_TAG=stable -COMPOSE_PROJECT_NAME=inventree-production +# Site URL - update this to match your host (and update the Caddyfile too!) +INVENTREE_SITE_URL="http://inventree.localhost" + +COMPOSE_PROJECT_NAME=inventree diff --git a/docker/Caddyfile b/docker/Caddyfile new file mode 100644 index 0000000000..ad7b2c26ba --- /dev/null +++ b/docker/Caddyfile @@ -0,0 +1,36 @@ +# Caddyfile for Inventree +# The following environment variables may be used: +# - INVENTREE_SITE_URL: The upstream URL of the Inventree site (default: inventree.localhost) +# - INVENTREE_SERVER: The internal URL of the Inventree container (default: http://inventree-server:8000) + +(log_common) { + log { + output file /var/log/caddy/{args.0}.access.log + } +} + +# Change the host to your domain (this will serve at inventree.localhost) +{$INVENTREE_SITE_URL:inventree.localhost} { + import log_common inventree + + encode gzip + + request_body { + max_size 100MB + } + + handle_path /static/* { + root * /var/www/static + file_server + } + + handle_path /media/* { + forward_auth {$INVENTREE_SERVER:"http://inventree-server:8000"} { + uri /auth/ + } + root * /var/www/media + file_server + } + + reverse_proxy {$INVENTREE_SERVER:"http://inventree-server:8000"} +} diff --git a/docker/docker-compose.sqlite.yml b/docker/docker-compose.sqlite.yml deleted file mode 100644 index 5e1a2df329..0000000000 --- a/docker/docker-compose.sqlite.yml +++ /dev/null @@ -1,64 +0,0 @@ -version: "3.8" - -# Docker compose recipe for InvenTree development server -# - Runs sqlite database -# - Uses built-in django webserver -# - Runs the InvenTree background worker process -# - Serves media and static content directly from Django webserver - -# IMPORTANT NOTE: -# The InvenTree docker image does not clone source code from git. -# Instead, you must specify *where* the source code is located, -# (on your local machine). -# The django server will auto-detect any code changes and reload the server. - -services: - - # InvenTree web server services - # Uses gunicorn as the web server - inventree-dev-server: - container_name: inventree-dev-server - build: - context: . - target: dev - # Cache the built image to be used by the inventree-dev-worker process - image: inventree-dev-image - ports: - # Expose web server on port 8000 - - 8000:8000 - volumes: - # Ensure you specify the location of the 'src' directory at the end of this file - - src:/home/inventree - environment: - - INVENTREE_DEBUG=True - - INVENTREE_DB_ENGINE=sqlite - - INVENTREE_DB_NAME=/home/inventree/db.sqlite3 - restart: unless-stopped - - # Background worker process handles long-running or periodic tasks - inventree-dev-worker: - container_name: inventree-dev-worker - image: inventree-dev-image - command: invoke worker - depends_on: - - inventree-dev-server - volumes: - # Ensure you specify the location of the 'src' directory at the end of this file - - src:/home/inventree - environment: - - INVENTREE_DEBUG=True - - INVENTREE_DB_ENGINE=sqlite - - INVENTREE_DB_NAME=/home/inventree/db.sqlite3 - restart: unless-stopped - -volumes: - # NOTE: Change "../" to a directory on your local machine, where the InvenTree source code is located - # Persistent data, stored external to the container(s) - src: - driver: local - driver_opts: - type: none - o: bind - # This directory specified where InvenTree source code is stored "outside" the docker containers - # By default, this directory is one level above the "docker" directory - device: ${INVENTREE_EXT_VOLUME:-../} diff --git a/docker/production/docker-compose.yml b/docker/docker-compose.yml similarity index 69% rename from docker/production/docker-compose.yml rename to docker/docker-compose.yml index 60650a8673..7b948cf7ab 100644 --- a/docker/production/docker-compose.yml +++ b/docker/docker-compose.yml @@ -39,6 +39,7 @@ services: # Use PostgreSQL as the database backend inventree-db: image: postgres:13 + container_name: inventree-db expose: - ${INVENTREE_DB_PORT:-5432}/tcp environment: @@ -48,13 +49,14 @@ services: - POSTGRES_DB=${INVENTREE_DB_NAME:?You must provide the 'INVENTREE_DB_NAME' variable in the .env file} volumes: # Map 'data' volume such that postgres database is stored externally - - inventree_data:/var/lib/postgresql/data/:z + - ${INVENTREE_EXT_VOLUME:?You must specify the 'INVENTREE_EXT_VOLUME' variable in the .env file!}:/var/lib/postgresql/data/:z restart: unless-stopped # redis acts as database cache manager # only runs under the "redis" profile : https://docs.docker.com/compose/profiles/ inventree-cache: image: redis:7.0 + container_name: inventree-cache depends_on: - inventree-db profiles: @@ -70,10 +72,8 @@ services: inventree-server: # If you wish to specify a particular InvenTree version, do so here image: inventree/inventree:${INVENTREE_TAG:-stable} + container_name: inventree-server # Only change this port if you understand the stack. - # If you change this you have to change: - # - the proxy settings (on two lines) - # - only change the exposed port - eg `1338:8000` if you want to expose the server on port 1338 expose: - 8000 depends_on: @@ -82,13 +82,14 @@ services: - .env volumes: # Data volume must map to /home/inventree/data - - inventree_data:/home/inventree/data:z + - ${INVENTREE_EXT_VOLUME}:/home/inventree/data:z restart: unless-stopped # Background worker process handles long-running or periodic tasks inventree-worker: # If you wish to specify a particular InvenTree version, do so here image: inventree/inventree:${INVENTREE_TAG:-stable} + container_name: inventree-worker command: invoke worker depends_on: - inventree-server @@ -96,37 +97,26 @@ services: - .env volumes: # Data volume must map to /home/inventree/data - - inventree_data:/home/inventree/data:z + - ${INVENTREE_EXT_VOLUME}:/home/inventree/data:z restart: unless-stopped - # nginx acts as a reverse proxy - # static files are served directly by nginx - # media files are served by nginx, although authentication is redirected to inventree-server - # web requests are redirected to gunicorn - # NOTE: You will need to provide a working nginx.conf file! + # caddy acts as reverse proxy and static file server + # https://hub.docker.com/_/caddy inventree-proxy: - image: nginx:stable + container_name: inventree-proxy + image: caddy:alpine + restart: always depends_on: - inventree-server + ports: + - ${INVENTREE_WEB_PORT:-80}:80 + - 443:443 env_file: - .env - ports: - # Default web port is 1337 (can be changed in the .env file) - - ${INVENTREE_WEB_PORT:-1337}:80 volumes: - # Provide nginx configuration file to the container - # Refer to the provided example file as a starting point - - ./nginx.prod.conf:/etc/nginx/conf.d/default.conf:ro,z - # nginx proxy needs access to static and media files - - inventree_data:/var/www:z - restart: unless-stopped - -volumes: - # Persistent data, stored external to the container(s) - inventree_data: - driver: local - driver_opts: - type: none - o: bind - # This directory specified where InvenTree data are stored "outside" the docker containers - device: ${INVENTREE_EXT_VOLUME:?You must specify the 'INVENTREE_EXT_VOLUME' variable in the .env file!} + - ./Caddyfile:/etc/caddy/Caddyfile:ro + - ${INVENTREE_EXT_VOLUME}/static:/var/www/static:z + - ${INVENTREE_EXT_VOLUME}/media:/var/www/media:z + - ${INVENTREE_EXT_VOLUME}:/var/log:z + - ${INVENTREE_EXT_VOLUME}:/data:z + - ${INVENTREE_EXT_VOLUME}:/config:z diff --git a/docker/install_build_packages.sh b/docker/install_build_packages.sh index 3ccb3d9370..ca7ea49ddf 100644 --- a/docker/install_build_packages.sh +++ b/docker/install_build_packages.sh @@ -7,5 +7,5 @@ apk add gcc g++ musl-dev openssl-dev libffi-dev cargo python3-dev openldap-dev \ jpeg-dev openjpeg-dev libwebp-dev zlib-dev \ sqlite sqlite-dev \ mariadb-connector-c-dev mariadb-client mariadb-dev \ - postgresql13-dev postgresql-libs postgresql13-client \ + postgresql13-dev postgresql-libs \ $@ diff --git a/docker/nginx.dev.conf b/docker/nginx.dev.conf deleted file mode 100644 index f919ab7e74..0000000000 --- a/docker/nginx.dev.conf +++ /dev/null @@ -1,66 +0,0 @@ - -server { - - # Listen for connection on (internal) port 80 - listen 80; - - real_ip_header proxy_protocol; - - location / { - - proxy_set_header Host $http_host; - proxy_set_header X-Forwarded-By $server_addr:$server_port; - proxy_set_header X-Forwarded-For $remote_addr; - proxy_set_header X-Forwarded-Proto $scheme; - proxy_set_header X-Real-IP $remote_addr; - proxy_set_header CLIENT_IP $remote_addr; - - proxy_pass_request_headers on; - - proxy_redirect off; - - client_max_body_size 100M; - - proxy_buffering off; - proxy_request_buffering off; - - # Change 'inventree-dev-server' to the name of the inventree server container, - # and '8000' to the INVENTREE_WEB_PORT (if not default) - proxy_pass http://inventree-dev-server:8000; - - } - - # Redirect any requests for static files - location /static/ { - alias /var/www/dev/static/; - autoindex on; - - # Caching settings - expires 30d; - add_header Pragma public; - add_header Cache-Control "public"; - } - - # Redirect any requests for media files - location /media/ { - alias /var/www/dev/media/; - - # Media files require user authentication - auth_request /auth; - - # Content header to force download - add_header Content-disposition "attachment"; - } - - # Use the 'user' API endpoint for auth - location /auth { - internal; - - proxy_pass http://inventree-dev-server:8000/auth/; - - proxy_pass_request_body off; - proxy_set_header Content-Length ""; - proxy_set_header X-Original-URI $request_uri; - } - -} diff --git a/docker/production/nginx.prod.conf b/docker/production/nginx.prod.conf deleted file mode 100644 index a78b9ebd0f..0000000000 --- a/docker/production/nginx.prod.conf +++ /dev/null @@ -1,67 +0,0 @@ - -server { - - # Listen for connection on (internal) port 80 - # If you are exposing this server to the internet, you should use HTTPS! - # In which case, you should also set up a redirect from HTTP to HTTPS, and listen on port 443 - # See the Nginx documentation for more details - listen 80; - - real_ip_header proxy_protocol; - - location / { - - proxy_set_header Host $http_host; - proxy_set_header X-Forwarded-By $server_addr:$server_port; - proxy_set_header X-Forwarded-For $remote_addr; - proxy_set_header X-Forwarded-Proto $scheme; - proxy_set_header X-Real-IP $remote_addr; - proxy_set_header CLIENT_IP $remote_addr; - - proxy_pass_request_headers on; - - proxy_redirect off; - - client_max_body_size 100M; - - proxy_buffering off; - proxy_request_buffering off; - - # Do not touch this unless you have a specific reason - this and the docker-compose need to match - proxy_pass http://inventree-server:8000; - } - - # Redirect any requests for static files - location /static/ { - alias /var/www/static/; - autoindex on; - - # Caching settings - expires 30d; - add_header Pragma public; - add_header Cache-Control "public"; - } - - # Redirect any requests for media files - location /media/ { - alias /var/www/media/; - - # Media files require user authentication - auth_request /auth; - - # Content header to force download - add_header Content-disposition "attachment"; - } - - # Use the 'user' API endpoint for auth - location /auth { - internal; - - proxy_pass http://inventree-server:8000/auth/; - - proxy_pass_request_body off; - proxy_set_header Content-Length ""; - proxy_set_header X-Original-URI $request_uri; - } - -} diff --git a/docker/requirements.txt b/docker/requirements.txt index cbfe5c853e..8450c5251b 100644 --- a/docker/requirements.txt +++ b/docker/requirements.txt @@ -17,3 +17,6 @@ gunicorn>=21.2.0 # LDAP required packages django-auth-ldap # Django integration for ldap auth python-ldap # LDAP auth support + +# Upgraded python package installer +uv diff --git a/docs/_includes/django.html b/docs/_includes/django.html new file mode 100644 index 0000000000..87046023f3 --- /dev/null +++ b/docs/_includes/django.html @@ -0,0 +1 @@ +https://docs.djangoproject.com/en/{{ config.extra.django_version }} diff --git a/docs/docs/develop/starting.md b/docs/docs/develop/starting.md index a47427ba19..f37f9d6ed9 100644 --- a/docs/docs/develop/starting.md +++ b/docs/docs/develop/starting.md @@ -8,16 +8,16 @@ As part of the larger project other languages/techniques are used, such as docke ### Getting started #### Getting to know the basics -The Django framework is a powerful tool for creating web applications. It is well documented and has a large community. The [Django documentation](https://docs.djangoproject.com/en/stable/) is a good place to start. +The Django framework is a powerful tool for creating web applications. It is well documented and has a large community. The [Django documentation]({% include "django.html" %}) is a good place to start. -In particular the [tutorial](https://docs.djangoproject.com/en/stable/intro/tutorial01/) is a good way to get to know the basics of Django. +In particular the [tutorial]({% include "django.html" %}/intro/tutorial01/) is a good way to get to know the basics of Django. InvenTree follows the best practies for Django so most of the contents should be applicable to InvenTree as well. The REST API is based on the [Django REST framework](https://www.django-rest-framework.org/). #### Setting up a development environment The recommended way to set up a development environment is to use VSCode devcontainers. The required files are provided with the repo, the docs are on a [dedicated page](./devcontainer.md). -It is also possible to use [docker development](../start/docker_dev.md) or [bare metal development](../start/bare_dev.md). With these you need to install the required dependencies manually with a dedicated task. +It is also possible to use [docker](../start/docker.md) or [bare metal development](../start/bare_dev.md). With these you need to install the required dependencies manually with a dedicated task. ```bash invoke setup-dev ``` diff --git a/docs/docs/extend/plugins.md b/docs/docs/extend/plugins.md index beaf60e485..16502ff9f1 100644 --- a/docs/docs/extend/plugins.md +++ b/docs/docs/extend/plugins.md @@ -85,7 +85,7 @@ The configuration entries must be enabled via the [InvenTree admin interface](.. ### Plugin Mixins -Common use cases are covered by pre-supplied modules in the form of *mixins* (similar to how [Django](https://docs.djangoproject.com/en/stable/topics/class-based-views/mixins/) does it). Each mixin enables the integration into a specific area of InvenTree. Sometimes it also enhances the plugin with helper functions to supply often used functions out-of-the-box. +Common use cases are covered by pre-supplied modules in the form of *mixins* (similar to how [Django]({% include "django.html" %}/topics/class-based-views/mixins/) does it). Each mixin enables the integration into a specific area of InvenTree. Sometimes it also enhances the plugin with helper functions to supply often used functions out-of-the-box. Supported mixin classes are: diff --git a/docs/docs/extend/plugins/app.md b/docs/docs/extend/plugins/app.md index d953b21da2..c9d42de0a7 100644 --- a/docs/docs/extend/plugins/app.md +++ b/docs/docs/extend/plugins/app.md @@ -7,4 +7,4 @@ title: App Mixin If this mixin is added to a plugin the directory the plugin class is defined in is added to the list of `INSTALLED_APPS` in the InvenTree server configuration. !!! warning "Danger Zone" - Only use this mixin if you have an understanding of djangos [app system](https://docs.djangoproject.com/en/stable/ref/applications). Plugins with this mixin are deeply integrated into InvenTree and can cause difficult to reproduce or long-running errors. Use the built-in testing functions of django to make sure your code does not cause unwanted behaviour in InvenTree before releasing. + Only use this mixin if you have an understanding of djangos [app system]({% include "django.html" %}/ref/applications). Plugins with this mixin are deeply integrated into InvenTree and can cause difficult to reproduce or long-running errors. Use the built-in testing functions of django to make sure your code does not cause unwanted behaviour in InvenTree before releasing. diff --git a/docs/docs/extend/plugins/metadata.md b/docs/docs/extend/plugins/metadata.md index abfe04a76c..216fe28fad 100644 --- a/docs/docs/extend/plugins/metadata.md +++ b/docs/docs/extend/plugins/metadata.md @@ -12,7 +12,7 @@ A much simpler and more accessible method of recording custom information agains ### MetadataMixin Class -*Most* of the models in the InvenTree database inherit from the `MetadataMixin` class, which adds the `metadata` field to each inheriting model. The `metadata` field is a [JSONField](https://docs.djangoproject.com/en/3.2/ref/models/fields/#django.db.models.JSONField) which allows for storing arbitrary JSON data against the model instance. +*Most* of the models in the InvenTree database inherit from the `MetadataMixin` class, which adds the `metadata` field to each inheriting model. The `metadata` field is a [JSONField]({% include "django.html" %}/ref/models/fields/#django.db.models.JSONField) which allows for storing arbitrary JSON data against the model instance. This field is provided to allow any plugins to store and retrieve arbitrary data against any item in the database. diff --git a/docs/docs/extend/plugins/urls.md b/docs/docs/extend/plugins/urls.md index 7122e66317..efa0ca8f7c 100644 --- a/docs/docs/extend/plugins/urls.md +++ b/docs/docs/extend/plugins/urls.md @@ -6,7 +6,7 @@ title: URLs Mixin Use the class constant `URLS` for a array of URLs that should be added to InvenTrees URL paths or override the `plugin.setup_urls` function. -The array has to contain valid URL patterns as defined in the [django documentation](https://docs.djangoproject.com/en/stable/topics/http/urls/). +The array has to contain valid URL patterns as defined in the [django documentation]({% include "django.html" %}/topics/http/urls/). ``` python class MyUrlsPlugin(UrlsMixin, InvenTreePlugin): @@ -19,14 +19,14 @@ class MyUrlsPlugin(UrlsMixin, InvenTreePlugin): ``` -The URLs get exposed under `/plugin/{plugin.slug}/*` and get exposed to the template engine with the prefix `plugin:{plugin.slug}:` (for usage with the [url tag](https://docs.djangoproject.com/en/stable/ref/templates/builtins/#url)). +The URLs get exposed under `/plugin/{plugin.slug}/*` and get exposed to the template engine with the prefix `plugin:{plugin.slug}:` (for usage with the [url tag]({% include "django.html" %}/ref/templates/builtins/#url)). !!! info "Note" In this example, when an HTTP request is made to `/plugin/{plugin.slug}/increase/.../...` the function `self.view_increase` is called and returns the view to be displayed (step 4 in the Django documentation) ### Views If your plugin will implement and host another webpage, familiarize yourself with Django views. Implementation is exactly the same. -A good place to start is the [django documentation](https://docs.djangoproject.com/en/4.2/topics/http/views/). Additional InvenTree-specific information is below. +A good place to start is the [django documentation]({% include "django.html" %}/topics/http/views/). Additional InvenTree-specific information is below. ### Rendering Views Rendering templated views is also supported. Templated HTML files should be placed inside your plugin folder in a sub folder called `templates`. diff --git a/docs/docs/faq.md b/docs/docs/faq.md index e4cf7d7f5c..b14acbef10 100644 --- a/docs/docs/faq.md +++ b/docs/docs/faq.md @@ -29,7 +29,7 @@ If the installed version of invoke is too old, users may see error messages duri - *'update' did not receive all required positional arguments!* - *Function has keyword-only arguments or annotations* -As per the [invoke guide](./start/intro.md#invoke), the minimum required version of Invoke is `2.0.0`. +As per the [invoke guide](./start/intro.md#invoke), the minimum required version of Invoke is `{{ config.extra.min_invoke_version }}`. To determine the version of invoke you have installed, run either: @@ -77,7 +77,7 @@ The most common problem here is that the correct sequenct of steps has not been For more information, refer to the installation guides: -- [Docker Installation](./start/docker_prod.md#updating-inventree) +- [Docker Installation](./start/docker_install.md#updating-inventree) - [Bare Metal Installation](./start/install.md#updating-inventree) !!! warning "Invoke Update" @@ -117,7 +117,7 @@ invoke worker ### File Sync Issues - Docker -When installing under [Docker](./start/docker.md), sometimes issues may arise keeping [persistent data](./start/docker.md#persistent-data) in sync. Refer to the [common issues](./start/docker_prod.md#common-issues) section in the docker setup guide for further details. +When installing under [Docker](./start/docker.md), sometimes issues may arise keeping [persistent data](./start/docker.md#persistent-data) in sync. Refer to the [common issues](./start/docker.md#common-issues) section in the docker setup guide for further details. ### Permission denied for mkdir: /home/inventree diff --git a/docs/docs/report/report.md b/docs/docs/report/report.md index e0ff863546..e82ac5ead6 100644 --- a/docs/docs/report/report.md +++ b/docs/docs/report/report.md @@ -25,7 +25,7 @@ Templates are rendered using standard HTML / CSS - if you are familiar with web ### Template Language -Uploaded report template files are passed through the [django template rendering framework](https://docs.djangoproject.com/en/dev/topics/templates/), and as such accept the same variable template strings as any other django template file. Different variables are passed to the report template (based on the context of the report) and can be used to customize the contents of the generated PDF. +Uploaded report template files are passed through the [django template rendering framework]({% include "django.html" %}/topics/templates/), and as such accept the same variable template strings as any other django template file. Different variables are passed to the report template (based on the context of the report) and can be used to customize the contents of the generated PDF. ### Variables @@ -77,7 +77,7 @@ Item: {{ item }} ``` !!! info "Conditionals" - Refer to the [django template language documentation](https://docs.djangoproject.com/en/dev/ref/templates/language/) for more information. + Refer to the [django template language documentation]({% include "django.html" %}/ref/templates/language/) for more information. ### Localization Issues @@ -278,7 +278,7 @@ Asset files can be rendered directly into the template as follows If the requested asset name does not match the name of an uploaded asset, the template will continue without loading the image. !!! info "Assets location" - You need to ensure your asset images to the report/assets directory in the [data directory](../start/docker_dev.md/#data-directory). Upload new assets via the [admin interface](../settings/admin.md) to ensure they are uploaded to the correct location on the server. + You need to ensure your asset images to the report/assets directory in the [data directory](../start/intro.md#file-storage). Upload new assets via the [admin interface](../settings/admin.md) to ensure they are uploaded to the correct location on the server. ## Report Snippets diff --git a/docs/docs/start/advanced.md b/docs/docs/start/advanced.md index 6bcc40873a..0d9032b105 100644 --- a/docs/docs/start/advanced.md +++ b/docs/docs/start/advanced.md @@ -94,7 +94,7 @@ This can be used to track usage and performance of the InvenTree backend and con If your InvenTree instance is used in a multi-site environment, you can enable multi-site support. Note that supporting multiple sites is well outside the scope of most InvenTree installations. If you know what you are doing, and have a good reason to enable multi-site support, you can do so by setting the `INVENTREE_SITE_MULTI` environment variable to `True`. !!! tip "Django Documentation" - For more information on multi-site support, refer to the [Django documentation](https://docs.djangoproject.com/en/3.2/ref/contrib/sites/). + For more information on multi-site support, refer to the [Django documentation]({% include "django.html" %}/ref/contrib/sites/). | Environment Variable | Config Key | Description | Default | | --- | --- | --- | --- | diff --git a/docs/docs/start/bare_prod.md b/docs/docs/start/bare_prod.md index de70572898..c08b8f03c1 100644 --- a/docs/docs/start/bare_prod.md +++ b/docs/docs/start/bare_prod.md @@ -9,7 +9,7 @@ title: Bare Metal Production Server The following instructions provide a reasonably performant server, using [gunicorn](https://gunicorn.org/) as a webserver, and [supervisor](http://supervisord.org/) as a process manager. -For alternative deployment methods, django apps provide multiple deployment methods - see the [Django documentation](https://docs.djangoproject.com/en/2.2/howto/deployment/). +For alternative deployment methods, django apps provide multiple deployment methods - see the [Django documentation]({% include "django.html" %}/howto/deployment/). There are also numerous online tutorials describing how to deploy a Django application either locally or on an online platform. @@ -102,10 +102,9 @@ In addition to the InvenTree server, you will need a method of delivering static ### Next Steps -You (or your system administrator) may wish to perform further steps such as placing the InvenTree server behind a reverse-proxy such as [nginx](https://www.nginx.com/). - +You (or your system administrator) may wish to perform further steps such as placing the InvenTree server behind a reverse-proxy such as [caddy](https://caddyserver.com/), or [nginx](https://www.nginx.com/). As production environment options are many and varied, such tasks are outside the scope of this documentation. There are many great online tutorials about running django applications in production! -As a starting point, you can refer to the [docker production example](./docker_prod.md) for a demonstration of running InvenTree behind a nginx proxy. +As a starting point, you can refer to the [docker guide](./docker.md) for a demonstration of running InvenTree behind a Caddy proxy. diff --git a/docs/docs/start/config.md b/docs/docs/start/config.md index 96e61bc8d5..1647e6fd38 100644 --- a/docs/docs/start/config.md +++ b/docs/docs/start/config.md @@ -1,28 +1,13 @@ --- -title: Database Configuration +title: InvenTree Configuration --- -## Database Configuration +## InvenTree Configuration While many InvenTree options can be configured at "run time", there are a number of system configuration parameters which need to be set *before* running InvenTree. Admin users will need to adjust the InvenTree installation to meet the particular needs of their setup. For example, pointing to the correct database backend, or specifying a list of allowed hosts. InvenTree system settings can be specified either via environment variables, or in a configuration file. -!!! info "Environment Variables" - Settings specified using environment variables take priority. Values provided in the configuration file are ignored if a matching environment variable is present. - -### Environment Variables - -In addition to specifying InvenTree options via the `config.yaml` file, these options can also be specified via environment variables. This can be usful for system administrators who want the flexibility of altering settings without editing the configuration file. - -Environment variable settings generally use the `INVENTREE_` prefix, and are all uppercase. - -!!! info "Configuration Priority" - Configuration options set via environment variables will take priority over the values set in the `config.yaml` file. - -!!! warning "Available Variables" - Some configuration options cannot be set via environment variables. Refer to the documentation below. - ### Configuration File To support install specific settings, a simple configuration file `config.yaml` is provided. This configuration file is loaded by the InvenTree server at runtime. Settings specific to a given install should be adjusted in `config.yaml`. @@ -43,7 +28,19 @@ The configuration file *template* can be found on [GitHub](https://github.com/in The default configuration file (as defined by the template linked above) will be copied to the specified configuration file location on first run, if a configuration file is not found in that location. !!! tip "Restart Server" - The contents of the configuration file are read when the InevnTree server first launches. If any changes are made to the configuration file, ensure that the server is restarted, so that the changes can be made operational. + The contents of the configuration file are read when the InvenTree server first launches. If any changes are made to the configuration file, ensure that the server is restarted, so that the changes can be made operational. + +### Environment Variables + +In addition to specifying InvenTree options via the `config.yaml` file, these options can also be specified via environment variables. This can be useful for system administrators who want the flexibility of altering settings without editing the configuration file. + +Environment variable settings generally use the `INVENTREE_` prefix, and are all uppercase. + +!!! info "Configuration Priority" + Configuration options set via environment variables will take priority over the values set in the `config.yaml` file. This can be useful for overriding specific settings without needing to edit the configuration file. + +!!! warning "Available Variables" + Some configuration options cannot be set via environment variables. Refer to the documentation below. ## Basic Options @@ -56,31 +53,52 @@ The following basic options are available: | INVENTREE_DB_LOGGING | db_logging | Enable logging of database messages | False | | INVENTREE_TIMEZONE | timezone | Server timezone | UTC | | INVENTREE_SITE_URL | site_url | Specify a fixed site URL | *Not specified* | -| INVENTREE_ADMIN_ENABLED | admin_enabled | Enable the [django administrator interface](https://docs.djangoproject.com/en/4.2/ref/contrib/admin/) | True | +| INVENTREE_ADMIN_ENABLED | admin_enabled | Enable the [django administrator interface]({% include "django.html" %}/ref/contrib/admin/) | True | | INVENTREE_ADMIN_URL | admin_url | URL for accessing [admin interface](../settings/admin.md) | admin | | INVENTREE_LANGUAGE | language | Default language | en-us | | INVENTREE_BASE_URL | base_url | Server base URL | *Not specified* | | INVENTREE_AUTO_UPDATE | auto_update | Database migrations will be run automatically | False | -### Admin Site +## Server Access -Django provides a powerful [administrator interface](https://docs.djangoproject.com/en/4.2/ref/contrib/admin/) which can be used to manage the InvenTree database. This interface is enabled by default, but can be disabled by setting `INVENTREE_ADMIN_ENABLED` to `False`. +Depending on how your InvenTree installation is configured, you will need to pay careful attention to the following settings. If you are running your server behind a proxy, or want to adjust support for CORS requests, one or more of the following settings may need to be adjusted. -#### Custom Admin URL +!!! warning "Advanced Users" + The following settings require a certain assumed level of knowledge. You should also refer to the [django documentation]({% include "django.html" %}/ref/settings/) for more information. -By default, the admin interface is available at the `/admin/` URL. This can be changed by setting the `INVENTREE_ADMIN_URL` environment variable. +!!! danger "Not Secure" + Allowing access from any host is not secure, and should be adjusted for your installation. + +!!! info "Environment Variables" + Note that a provided environment variable will override the value provided in the configuration file. + +!!! success "INVENTREE_SITE_URL" + If you have specified the `INVENTREE_SITE_URL`, this will automatically be used as a trusted CSRF and CORS host (see below). + +| Environment Variable | Configuration File | Description | Default | +| --- | --- | --- | --- | +| INVENTREE_ALLOWED_HOSTS | allowed_hosts | List of allowed hosts | `*` | +| INVENTREE_TRUSTED_ORIGINS | trusted_origins | List of trusted origins. Refer to the [django documentation]({% include "django.html" %}/ref/settings/#csrf-trusted-origins) | Uses the *INVENTREE_SITE_URL* parameter, if set. Otherwise, an empty list. | +| INVENTREE_CORS_ORIGIN_ALLOW_ALL | cors.allow_all | Allow all remote URLS for CORS checks | False | +| INVENTREE_CORS_ORIGIN_WHITELIST | cors.whitelist | List of whitelisted CORS URLs. Refer to the [django-cors-headers documentation](https://github.com/adamchainz/django-cors-headers#cors_allowed_origins-sequencestr) | Uses the *INVENTREE_SITE_URL* parameter, if set. Otherwise, an empty list. | +| INVENTREE_USE_X_FORWARDED_HOST | use_x_forwarded_host | Use forwarded host header | False | +| INVENTREE_USE_X_FORWARDED_PORT | use_x_forwarded_port | Use forwarded port header | False | +| INVENTREE_CORS_ALLOW_CREDENTIALS | cors.allow_credentials | Allow cookies in cross-site requests | True | + +## Admin Site + +Django provides a powerful [administrator interface]({% include "django.html" %}/ref/contrib/admin/) which can be used to manage the InvenTree database. This interface is enabled by default, and available at the `/admin/` URL. + +The following admin site configuration options are available: + +| Environment Variable | Configuration File | Description | Default | +| --- | --- | --- | --- | +| INVENTREE_ADMIN_ENABLED | admin_enabled | Enable the django administrator interface | True | +| INVENTREE_ADMIN_URL | admin_url | URL for accessing the admin interface | admin | !!! warning "Security" Changing the admin URL is a simple way to improve security, but it is not a substitute for proper security practices. -### Base URL Configuration - -The base URL of the InvenTree site is required for constructing absolute URLs in a number of circumstances. To construct a URL, the InvenTree iterates through the following options in decreasing order of importance: - -1. Static configuration (i.e. set using environment variable or configuration file as above) -2. Global settings (i.e. configured at run-time in the [global settings](../settings/global.md)) -3. Using the hostname supplied by the user request - ## Administrator Account An administrator account can be specified using the following environment variables: @@ -196,32 +214,6 @@ A list of currency codes (e.g. *AUD*, *CAD*, *JPY*, *USD*) can be specified usin !!! tip "More Info" Read the [currencies documentation](../settings/currency.md) for more information on currency support in InvenTree -## Server Access - -Depending on how your InvenTree installation is configured, you will need to pay careful attention to the following settings. If you are running your server behind a proxy, or want to adjust support for CORS requests, one or more of the following settings may need to be adjusted. - -!!! warning "Advanced Users" - The following settings require a certain assumed level of knowledge. You should also refer to the [django documentation](https://docs.djangoproject.com/en/4.2/ref/settings/) for more information. - -!!! danger "Not Secure" - Allowing access from any host is not secure, and should be adjusted for your installation. - -!!! info "Environment Variables" - Note that a provided environment variable will override the value provided in the configuration file. - -!!! success "INVENTREE_SITE_URL" - If you have specified the `INVENTREE_SITE_URL`, this will automatically be used as a trusted CSRF and CORS host (see below). - -| Environment Variable | Configuration File | Description | Default | -| --- | --- | --- | --- | -| INVENTREE_ALLOWED_HOSTS | allowed_hosts | List of allowed hosts | `*` | -| INVENTREE_TRUSTED_ORIGINS | trusted_origins | List of trusted origins. Refer to the [django documentation](https://docs.djangoproject.com/en/4.2/ref/settings/#csrf-trusted-origins) | Uses the *INVENTREE_SITE_URL* parameter, if set. Otherwise, an empty list. | -| INVENTREE_CORS_ORIGIN_ALLOW_ALL | cors.allow_all | Allow all remote URLS for CORS checks | False | -| INVENTREE_CORS_ORIGIN_WHITELIST | cors.whitelist | List of whitelisted CORS URLs. Refer to the [django-cors-headers documentation](https://github.com/adamchainz/django-cors-headers#cors_allowed_origins-sequencestr) | Uses the *INVENTREE_SITE_URL* parameter, if set. Otherwise, an empty list. | -| INVENTREE_USE_X_FORWARDED_HOST | use_x_forwarded_host | Use forwarded host header | False | -| INVENTREE_USE_X_FORWARDED_PORT | use_x_forwarded_port | Use forwarded port header | False | -| INVENTREE_CORS_ALLOW_CREDENTIALS | cors.allow_credentials | Allow cookies in cross-site requests | True | - ## File Storage Locations InvenTree requires some external directories for storing files: @@ -230,6 +222,7 @@ InvenTree requires some external directories for storing files: | --- | --- | --- | --- | | INVENTREE_STATIC_ROOT | static_root | [Static files](./serving_files.md#static-files) directory | *Not specified* | | INVENTREE_MEDIA_ROOT | media_root | [Media files](./serving_files.md#media-files) directory | *Not specified* | +| INVENTREE_BACKUP_DIR | backup_dir | Backup files directory | *Not specified* | !!! tip "Serving Files" Read the [Serving Files](./serving_files.md) section for more information on hosting *static* and *media* files @@ -298,7 +291,7 @@ The InvenTree server can be integrated with the [sentry.io](https://sentry.io) m !!! info "Default DSN" If enabled with the default DSN, server errors will be logged to a sentry.io account monitored by the InvenTree developers. -### Customisation Options +### Customization Options The logo and custom messages can be changed/set: @@ -327,9 +320,3 @@ The following [plugin](../extend/plugins.md) configuration options are available | INVENTREE_PLUGIN_NOINSTALL | plugin_noinstall | Disable Plugin installation via API - only use plugins.txt file | False | | INVENTREE_PLUGIN_FILE | plugins_plugin_file | Location of plugin installation file | *Not specified* | | INVENTREE_PLUGIN_DIR | plugins_plugin_dir | Location of external plugin directory | *Not specified* | - -## Other Options - -### Middleware - -Custom middleware layers can be specified here. diff --git a/docs/docs/start/docker.md b/docs/docs/start/docker.md index 798d8ccf08..4a3e3458d3 100644 --- a/docs/docs/start/docker.md +++ b/docs/docs/start/docker.md @@ -2,18 +2,24 @@ title: Docker Setup --- -## Docker Image +## Docker Installation Guide + +The information on this page serves as useful theory and background information for setting up InvenTree using docker. + +!!! tip "Docker Install" + To jump right into the installation process, refer to the [docker installation guide](./docker_install.md) + +## Docker Theory The most convenient method of installing and running InvenTree is to use the official [docker image](https://hub.docker.com/r/inventree/inventree), available from docker-hub. -The InvenTree docker image contains all the required system packages, python modules, and configuration files for running a containerised InvenTree web server. - -!!! tip "Compose Yourself" - The InvenTree container requires linking with other docker containers (such as a database backend) for complete operation. Sample [docker compose](#docker-compose) scripts are provided to get you up and running +The InvenTree docker image contains all the required system packages, python modules, and configuration files for running a containerized InvenTree production installation. +!!! tip "Docker Compose" + The InvenTree container requires linking with other docker containers (such as a database backend, and a file server) for complete operation. Refer to the [docker compose](#docker-compose) instructions to get up and running !!! warning "Check the version" - Please make sure you are reading the [STABLE](https://docs.inventree.org/en/stable/start/docker_prod/) documentation when using the stable docker image tags. + Please make sure you are reading the [STABLE](https://docs.inventree.org/en/stable/start/docker/) documentation when using the stable docker image tags. !!! warning "Assumed Knowledge" A very basic understanding of [Docker](https://www.docker.com/) and [docker compose](https://docs.docker.com/compose/) is assumed, for the following setup guides. @@ -26,16 +32,11 @@ Pre-built Docker images are available from [dockerhub](https://hub.docker.com/r/ | --- | --- | --- | | **inventree:stable** | The most recent *stable* release version of InvenTree | [stable docs](https://docs.inventree.org/en/stable/start/docker/) | | **inventree:latest** | The most up-to-date *development* version of InvenTree. | [latest docs](https://docs.inventree.org/en/latest/start/docker/) | -| **inventree:_tag_** | Specific tagged images are built for each tagged release of InvenTree, e.g. `inventree:0.7.3`| https://docs.inventree.org/en/INSERT_YOUR_TAG_HERE/start/docker/ | +| **inventree:_tag_** | Specific tagged images are built for each tagged release of InvenTree, e.g. `inventree:0.7.3`| *Refer to specific InvenTree version* | ### Docker Compose -The InvenTree docker image provides a containerized webserver, however it *must* be connected with other containers (at the very least, a database backend). - -InvenTree provides sample docker compose files to get you up and running: - -- A [development](#development-server) compose file provides a simple way to spin up a development environment -- A [production](#production-server) compose file is intended to be used in a production environment, running the web server behind a nginx proxy. +The InvenTree docker image provides a containerized webserver, however it *must* be connected with other containers to function. ### Environment Variables @@ -77,14 +78,82 @@ Plugins are supported natively when running under docker. There are two ways to - Install via the `plugins.txt` file provided in the external data directory - Install into the `plugins/` subdirectory in the external data directory -## Docker Setup Guides +## Docker Compose -With these basics in mind, refer to the following installation guides: +[docker compose](https://docs.docker.com/compose/) is used to sequence all the required containerized processes. -### Production Server +### Static and Media Files -Refer to the [docker production server setup guide](./docker_prod.md) for instructions on configuring a production server using docker. +The production docker compose configuration outlined on this page uses [Caddy](https://caddyserver.com/) to serve static files and media files. If you change this configuration, you will need to ensure that static and media files are served correctly. -### Development Server +!!! info "Read More" + Refer to the [Serving Files](./serving_files.md) section for more details -Refer to the [docker development server setup guide](./docker_dev.md) for instructions on configuring a development server using docker. +### SSL Certificates + +The provided `Caddyfile` configuration file is setup to enable [Automatic HTTPS](https://caddyserver.com/docs/automatic-https) by default! All you have to do is specify a `https://` URL in the `INVENTREE_SITE_URL` variable. + +### Containers + +The example docker compose file launches the following containers: + +| Container | Description | +| --- | --- | +| inventree-db | PostgreSQL database | +| inventree-server | Gunicorn web server | +| inventree-worker | django-q background worker | +| inventree-proxy | Caddy file server and reverse proxy | +| *inventree-cache* | *redis cache (optional)* | + +#### PostgreSQL Database + +A PostgreSQL database container which requires a username:password combination (which can be changed). This uses the official [PostgreSQL image](https://hub.docker.com/_/postgres). + +#### Web Server + +Runs an InvenTree web server instance, powered by a Gunicorn web server. + +#### Background Worker + +Runs the InvenTree background worker process. This spins up a second instance of the *inventree* container, with a different entrypoint command. + +#### File Server + +Caddy working as a reverse proxy, separating requests for static and media files, and directing everything else to Gunicorn. + +This container uses the official [caddy image](https://hub.docker.com/_/caddy). + +#### Redis Cache + +Redis is used as cache storage for the InvenTree server. This provides a more performant caching system which can useful in larger installations. + +This container uses the official [redis image](https://hub.docker.com/_/redis). + +!!! info "Redis on Docker" + Docker adds an additional network layer - that might lead to lower performance than bare metal. + To optimize and configure your redis deployment follow the [official docker guide](https://redis.io/docs/getting-started/install-stack/docker/#configuration). + +!!! warning "Disabled by default" + The *redis* container is not enabled in the default configuration. This is provided as an example for users wishing to use redis. + To enable the *redis* container, run any `docker compose` commands with the `--profile redis` flag. + You will also need to un-comment the `INVENTREE_CACHE_<...>` variables in the `.env` file. + +### Data Volume + +InvenTree stores any persistent data (e.g. uploaded media files, database data, etc) in a [volume](https://docs.docker.com/storage/volumes/) which is mapped to a local system directory. The location of this directory must be configured in the `.env` file, specified using the `INVENTREE_EXT_VOLUME` variable. + +!!! info "Data Directory" + Make sure you change the path to the local directory where you want persistent data to be stored. + +## Common Issues + +### Volume Mapping + +When configuring a docker install, sometimes a misconfiguration can cause peculiar issues where it seems that the installation is functioning correctly, but uploaded files and plugins do not "persist" across sessions. In such cases, the "mounted" volume has not mapped to a directory on your local filesystem. This may occur if you have tried multiple setup options without clearing existing volume bindings. + +!!! tip "Start with a clean slate" + To prevent such issues, it is recommended that you start with a "clean slate" if you have previously configured an InvenTree installation under docker. + +If you have previously setup InvenTree, remove existing volume bindings using the following command: + +```docker volume rm -f inventree-production_inventree_data``` diff --git a/docs/docs/start/docker_dev.md b/docs/docs/start/docker_dev.md deleted file mode 100644 index 289e6306e3..0000000000 --- a/docs/docs/start/docker_dev.md +++ /dev/null @@ -1,241 +0,0 @@ ---- -title: Docker Development Server ---- - -## Docker Development Server - -You can use docker to launch and manage a development server, in a similar fashion to managing a production server. - -The InvenTree dockerfile (`./Dockerfile`) uses a [multi-stage build](https://docs.docker.com/develop/develop-images/multistage-build/) process to allow both production and development setups from the same image. - -There are some key differences compared to the [docker production setup](./docker_prod.md): - -- The docker image is built locally, rather than being downloaded from DockerHub -- The docker image points to the source code on your local machine (mounted as a 'volume' in the docker container) -- The django webserver is used, instead of running behind Gunicorn -- The server will automatically reload when code changes are detected - -!!! info "Static and Media Files" - The development server runs in DEBUG mode, and serves static and media files natively. - -!!! info "Hacker Mode" - The following setup guide starts a development server which will reload "on the fly" as changes are made to the source code. This is designed for programmers and developers who wish to add and test new InvenTree features. - -### Data Directory - -Persistent data (such as the stored database, media files, configuration files, etc) will be stored in the `./data` directory (relative to the InvenTree source code directory). - -- This directory is automatically created when you launch InvenTree via docker -- This directory is excluded from git version tracking - -## Quickstart Guide - -To get "up and running" with a development environment, complete with a set of [demo data](https://github.com/inventree/demo-dataset) to work with, run the following commands: - -```bash -git clone https://github.com/inventree/InvenTree.git && cd InvenTree -docker compose run inventree-dev-server invoke update -docker compose run inventree-dev-server invoke setup-test --dev -docker compose up -d -``` - -!!! tip "Development Server" - You can then view the development server at [http://localhost:8000](http://localhost:8000) - -!!! info "Details, details" - For a more in-depth setup guide, continue reading below! - -## Development Setup Guide - -To get started with an InvenTree development setup, follow the simple steps outlined below. Before continuing, ensure that you have completed the following steps: - -- Downloaded the InvenTree source code to your local machine -- Installed docker on your local machine (install *Docker Desktop* on Windows) -- Have a terminal open to the root directory of the InvenTree source code - -### Edit Environment Variables (Optional) - -If desired, the user may edit the environment variables, located in the `.env` file. - -!!! success "This step is optional" - This step can be skipped, as the default variables will work just fine! - -!!! info "Database Credentials" - You may also wish to change the database username (`INVENTREE_DB_USER`) and password (`INVENTREE_DB_PASSWORD`) from their default values - -### Perform Initial Setup - -Perform the initial database setup by running the following command: - -```bash -docker compose run inventree-dev-server invoke update -``` - -If this is the first time you are configuring the development server, this command will build a development version of the inventree docker image. - -This command also performs the following steps: - -- Ensure required python packages are installed -- Perform the required schema updates to create the required database tables -- Update translation files -- Collect all required static files into a directory where they can be served by nginx - -!!! info "Grab a coffee" - This initial build process may take a few minutes! - -### Import Demo Data - -To fill the database with a demo dataset, run the following command: - -```bash -docker compose run inventree-dev-server invoke setup-test --dev -``` - -### Start Docker Containers - -Now that the database has been created, and migrations applied, we are ready to launch the InvenTree containers: - -```bash -docker compose up -d -``` - -### Create Admin Account - -If you are creating the initial database, you need to create an admin (superuser) account for the database. Run the command below, and follow the prompts: - -!!! info "Containers must be running" - For the `invoke superuser` command to execute properly, ensure you have run the `docker compose up -d` command. - -```bash -docker compose run inventree-dev-server invoke superuser -``` - -This command launches the remaining containers: - -- `inventree-dev-server` - InvenTree web server -- `inventree-dev-worker` - Background worker - -!!! success "Check Connection" - Check that the server is running at [http://localhost:8000](http://localhost:8000). The server may take a few minutes to be ready. - -## Running commands in the container - -Using `docker compose run [...]` commands creates a new container to run this specific command. -This will eventually clutter your docker with many dead containers that take up space on the system. - -You can access the running containers directly with the following: -```bash -docker exec -it inventree-dev-server /bin/bash -``` - -You then run the following to access the virtualenv: -```bash -source data/env/bin/activate -``` - -This sets up a bash terminal where you can run `invoke` commands directly. - -!!! warning "Tests" - Running `invoke test` in your currently active inventree-dev-server container may result in tests taking longer than usual. - -### Cleaning up old containers - -If you have Docker Desktop installed, you will be able to remove containers directly in the GUI. -Your active containers are grouped under "inventree" in Docker Desktop. -The main dev-server, dev-db, and dev-worker containers are all listed without the "inventree" prefix. -One time run containers, like those executed via `docker compose run [...]` are suffixed with `run-1a2b3c4d5e6f` where the hex string varies. - -To remove such containers, either click the garbage bin on the end of the line, or mark the containers, and click the delete button that shows up. -This is the recommended procedure for container cleanup. - -#### Advanced cleanup -!!! warning "Advanced users only" - This section requires good knowledge of Docker and how it operates. - Never perform these commands if you do not understand what they do - -If you're running a container with the general boilerplate commands used with invoke (invoke test, invoke update, etc) and no custom parameters or execution, you can add the `--rm` flag to `docker compose run`, and the container will delete itself when it goes down. -Do note that any data not stored in a volume, i.e. only in the container, will be lost when the container stops. - -To clean out old containers using the command line, follow this guide: - -Run the following command: -```bash -docker ps -a --filter status=exited -``` - -This gives you a list of all stopped containers. -Find the containers you wish to delete, copy the container IDs and add them to this command: - -```bash -docker rm [ID1] [ID2] [IDn] -``` -When executed, this removes all containers whose IDs were pasted. - -!!! warning "Execute at own risk" - The command below does not forgive errors. - Execute this only if you know what you're doing - -Running this command will remove **all** stopped one-time run InvenTree containers matching parameters: -```bash -docker container prune --filter label="com.docker.compose.oneoff=True" --filter label="com.docker.compose.service=inventree-dev-server" -``` - -The following output will appear: -``` -WARNING! This will remove all stopped containers. -Are you sure you want to continue? [y/N] y -Deleted Containers: -[IDs of any container that was deleted, one per line] -``` - -## Restarting Services - -Once initial setup is complete, stopping and restarting the services is much simpler: - -### Stop InvenTree Services - -To stop the InvenTree development server, simply run the following command: - -``` -docker compose down -``` - -### Start InvenTree Services - -To start the InvenTree development server, simply run the following command: - -``` -docker compose up -d -``` - -### Restart InvenTree Services - -A restart cycle is as simple as: - -``` -docker compose restart -``` - -## Editing InvenTree Source - -Any changes made to the InvenTree source code are automatically detected by the services running under docker. - -Thus, you can freely edit the InvenTree source files in your editor of choice. - -### Database Updates - -Any updates which require a database schema change must be reflected in the database itself. - -To run database migrations inside the docker container, run the following command: - -``` -docker compose run inventree-dev-server invoke update -``` - -### Docker Image Updates - -Occasionally, the docker image itself may receive some updates. In these cases, it may be required that the image is rebuilt. To perform a complete rebuild of the InvenTree development image from local source, run the following command: - -``` -docker compose build --no-cache -``` diff --git a/docs/docs/start/docker_install.md b/docs/docs/start/docker_install.md new file mode 100644 index 0000000000..85506622da --- /dev/null +++ b/docs/docs/start/docker_install.md @@ -0,0 +1,211 @@ +--- +title: Docker Production Server +--- + +## Docker Production Server + +The following guide provides a streamlined production InvenTree installation, with minimal configuration required. + +!!! tip "Docker Installation" + This guide assumes that you have already installed [Docker](https://www.docker.com/) and [Docker Compose](https://docs.docker.com/compose/). If you have not yet installed Docker, please refer to the [official installation guide](https://docs.docker.com/get-docker/). + +!!! info "Starting Point" + This setup guide should be considered a *starting point* - your particular production requirements vary from the example shown here. + +!!! tip "Docker Theory" + Refer to the [docker theory section](./docker.md) for more information about how our docker installation works under the hood. + +### Before You Start + +!!! warning "Check the version" + Please make sure you are reading the [STABLE](https://docs.inventree.org/en/stable/start/docker/) documentation when using the stable docker image tags. + +!!! warning "Docker Knowledge Required" + This guide assumes that you are reasonably comfortable with the basic concepts of docker and docker compose. + +## Docker Installation + +### Required Files + +The following files required for this setup are provided with the InvenTree source, located in the `./docker/` directory of the [InvenTree source code](https://github.com/inventree/InvenTree/tree/master/docker/production): + +| Filename | Description | +| --- | --- | +| [docker-compose.yml](https://github.com/inventree/InvenTree/blob/master/docker/docker-compose.yml) | The docker compose script | +| [.env](https://github.com/inventree/InvenTree/blob/master/docker/.env) | Environment variables | +| [Caddyfile](https://github.com/inventree/InvenTree/blob/master/docker/Caddyfile) | Caddy configuration file | + +Download these files to a directory on your local machine. + +!!! success "Working Directory" + This tutorial assumes you are working from a direction where all of these files are located. + +!!! tip "No Source Required" + For a production setup you do not need the InvenTree source code. Simply download the three required files from the links above! + +### Edit Environment Variables + +The first step is to edit the environment variables, located in the `.env` file. + +!!! warning "External Volume" + You must define the `INVENTREE_EXT_VOLUME` variable - this must point to a directory *on your local machine* where persistent data is to be stored. + +!!! warning "Database Credentials" + You must also define the database username (`INVENTREE_DB_USER`) and password (`INVENTREE_DB_PASSWORD`). You should ensure they are changed from the default values for added security + +!!! info "Other Variables" + There are a number of other environment variables which can be set to customize the InvenTree installation. Refer to the [environment variables](./config.md) documentation for more information. + +### Initial Database Setup + +Perform the initial database setup by running the following command: + +```bash +docker compose run --rm inventree-server invoke update +``` + +This command performs the following steps: + +- Ensure required python packages are installed +- Create a new (empty) database +- Perform the required schema updates to create the required database tables +- Update translation files +- Update required static files + +### Create Administrator Account + +If you are creating the initial database, you need to create an admin (superuser) account for the database. Run the command below, and follow the prompts: + +``` +docker compose run inventree-server invoke superuser +``` + +Alternatively, admin account details can be specified in the `.env` file, removing the need for this manual step: + +| Variable | Description | +| --- | --- | +| INVENTREE_ADMIN_USER | Admin account username | +| INVENTREE_ADMIN_PASSWORD | Admin account password | +| INVENTREE_ADMIN_EMAIL | Admin account email address | + +!!! warning "Scrub Account Data" + Ensure that the admin account credentials are removed from the `.env` file after the first run, for security. + +### Start Docker Containers + +Now that the database has been created, migrations applied, and you have created an admin account, we are ready to launch the InvenTree containers: + +``` +docker compose up -d +``` + +This command launches the following containers: + +- `inventree-db` - PostgreSQL database +- `inventree-server` - InvenTree web server +- `inventree-worker` - Background worker +- `inventree-proxy` - Caddy reverse proxy + +!!! success "Up and Running!" + You should now be able to view the InvenTree login screen at [http://inventree.localhost](http://inventree.localhost) (or whatever custom domain you have configured in the `.env` file). + +## Updating InvenTree + +To update your InvenTree installation to the latest version, follow these steps: + +### Stop Containers + +Stop all running containers as below: + +``` +docker compose down +``` + +### Update Images + +Pull down the latest version of the InvenTree docker image + +``` +docker compose pull +``` + +This ensures that the InvenTree containers will be running the latest version of the InvenTree source code. + +!!! tip "Docker Directory" + All `docker compose` commands must be performed in the same directory as the [docker-compose.yml file](#required-files) + +!!! info "Tagged Version" + If you are targeting a particular "tagged" version of InvenTree, you may wish to edit the `INVENTREE_TAG` variable in the `.env` file before issuing the `docker compose pull` command + +### Update Database + +Run the following command to ensure that the InvenTree database is updated: + +``` +docker compose run --rm inventree-server invoke update +``` + +!!! info "Skip Backup" + By default, the `invoke update` command performs a database backup. To skip this step, add the `--skip-backup` flag + +### Start Containers + +Now restart the docker containers: + +``` +docker compose up -d +``` + +## Data Backup + +Database and media files are stored external to the container, in the volume location specified in the `docker-compose.yml` file. It is strongly recommended that a backup of the files in this volume is performed on a regular basis. + +Read more about [data backup](./backup.md). + +### Exporting Database as JSON + +To export the database to an agnostic JSON file, perform the following command: + +``` +docker compose run --rm inventree-server invoke export-records -f /home/inventree/data/data.json +``` + +This will export database records to the file `data.json` in your mounted volume directory. + +## Further Configuration + +### Custom Domain + +By default, the InvenTree server is accessible at [http://inventree.localhost](http://inventree.localhost). If you wish to use a custom domain, you can edit the `.env` environment file to specify the domain name. + +Look for the `INVENTREE_SITE_URL` variable, and set it to the desired domain name. + +!!! tip "Configuration Options" + There are a number of other environment variables which can be set to customize the InvenTree installation. Refer to the [configuration documentation](./config.md) for more information. + +### SSL Configuration + +The provided `Caddyfile` configuration file is setup to enable [Automatic HTTPS](https://caddyserver.com/docs/automatic-https) "out of the box". All you have to do is specify a `https://` URL in the `INVENTREE_SITE_URL` variable. + + +The [Caddy](./docker.md#ssl-certificates) container will automatically generate SSL certificates for your domain. + +#### Persistent Files + +Any persistent files generated by the Caddy container (such as certificates, etc) will be stored in the `caddy` directory within the external volume. + +### Demo Dataset + +To quickly get started with a demo dataset, you can run the following command: + +``` +docker compose run --rm inventree-server invoke setup-test -i +``` + +This will install the InvenTree demo dataset into your instance. + +To start afresh (and completely remove the existing database), run the following command: + +``` +docker compose run --rm inventree-server invoke delete-data +``` diff --git a/docs/docs/start/docker_prod.md b/docs/docs/start/docker_prod.md deleted file mode 100644 index a29e50b40a..0000000000 --- a/docs/docs/start/docker_prod.md +++ /dev/null @@ -1,247 +0,0 @@ ---- -title: Docker Production Server ---- - -## Docker Production Server - -The following guide provides a streamlined production InvenTree installation, with minimal configuration required. - -!!! info "Starting Point" - This setup guide should be considered a *starting point*. It is likely that your particular production requirements will vary from the example shown here. - -### Before You Start - -!!! warning "Check the version" - Please make sure you are reading the [STABLE](https://docs.inventree.org/en/stable/start/docker_prod/) documentation when using the stable docker image tags. - -!!! warning "Docker Skills Required" - This guide assumes that you are reasonably comfortable with the basic concepts of docker and docker compose. - -#### Docker Image - -This production setup guide uses the official InvenTree docker image, available from dockerhub. - -!!! info "Stable Version" - The provided docker compose file targets `inventree:stable` by default. - -#### Docker Compose - -A sample [docker compose file](https://github.com/inventree/InvenTree/blob/master/docker/production/docker-compose.yml) is provided to sequence all the required processes. - -!!! tip "Starting Point" - If you require a different configuration, use this docker compose file as a starting point. - -#### Static and Media Files - -The sample docker compose configuration outlined on this page uses nginx to serve static files and media files. If you change this configuration, you will need to ensure that static and media files are served correctly. - -!!! info "Read More" - Refer to the [Serving Files](./serving_files.md) section for more details - -#### Required Files - -The following files required for this setup are provided with the InvenTree source, located in the `./docker/production` directory of the [InvenTree source code](https://github.com/inventree/InvenTree/tree/master/docker/production): - -| Filename | Description | -| --- | --- | -| [docker-compose.yml](https://github.com/inventree/InvenTree/blob/master/docker/production/docker-compose.yml) | The docker compose script | -| [.env](https://github.com/inventree/InvenTree/blob/master/docker/production/.env) | Environment variables | -| [nginx.prod.conf](https://github.com/inventree/InvenTree/blob/master/docker/production/nginx.prod.conf) | nginx proxy configuration file | - -This tutorial assumes you are working from the `./docker/production` directory. If this is not the case, ensure that these required files are all located in your working directory. - -!!! tip "No Source Required" - For a production setup you do not need the InvenTree source code. Simply download the three required files from the links above! - -### Containers - -The example docker compose file launches the following containers: - -| Container | Description | -| --- | --- | -| inventree-db | PostgreSQL database | -| inventree-server | Gunicorn web server | -| inventree-worker | django-q background worker | -| inventree-proxy | nginx proxy server | -| *inventree-cache* | *redis cache (optional)* | - -#### PostgreSQL Database - -A PostgreSQL database container which requires a username:password combination (which can be changed). This uses the official [PostgreSQL image](https://hub.docker.com/_/postgres). - -#### Web Server - -Runs an InvenTree web server instance, powered by a Gunicorn web server. - -#### Background Worker - -Runs the InvenTree background worker process. This spins up a second instance of the *inventree* container, with a different entrypoint command. - -#### Nginx Proxy - -Nginx working as a reverse proxy, separating requests for static and media files, and directing everything else to Gunicorn. - -This container uses the official [nginx image](https://hub.docker.com/_/nginx). - -#### Redis Cache - -Redis is used as cache storage for the InvenTree server. This provides a more performant caching system which can useful in larger installations. - -This container uses the official [redis image](https://hub.docker.com/_/redis). - -!!! info "Redis on Docker" - Docker adds an additional network layer - that might lead to lower performance than bare metal. - To optimize and configure your redis deployment follow the [official docker guide](https://redis.io/docs/getting-started/install-stack/docker/#configuration). - -!!! warning "Disabled by default" - The *redis* container is not enabled in the default configuration. This is provided as an example for users wishing to use redis. - To enable the *redis* container, run any `docker compose` commands with the `--profile redis` flag. - You will also need to un-comment the `INVENTREE_CACHE_<...>` variables in the `.env` file. - -### Data Volume - -InvenTree stores any persistent data (e.g. uploaded media files, database data, etc) in a [volume](https://docs.docker.com/storage/volumes/) which is mapped to a local system directory. The location of this directory must be configured in the `.env` file, specified using the `INVENTREE_EXT_VOLUME` variable. - -!!! info "Data Directory" - Make sure you change the path to the local directory where you want persistent data to be stored. - -#### Common Issues - -When configuring a docker install, sometimes a misconfiguration can cause peculiar issues where it seems that the installation is functioning correctly, but uploaded files and plugins do not "persist" across sessions. In such cases, the "mounted" volume has not mapped to a directory on your local filesystem. This may occur if you have tried multiple setup options without clearing existing volume bindings. - -!!! tip "Start with a clean slate" - To prevent such issues, it is recommended that you start with a "clean slate" if you have previously configured an InvenTree installation under docker. - -If you have previously setup InvenTree, remove existing volume bindings using the following command: - -```docker volume rm -f inventree-production_inventree_data``` - - -## Production Setup Guide - -### Edit Environment Variables - -The first step is to edit the environment variables, located in the `.env` file. - -!!! warning "External Volume" - You must define the `INVENTREE_EXT_VOLUME` variable - this must point to a directory *on your local machine* where persistent data is to be stored. - -!!! warning "Database Credentials" - You must also define the database username (`INVENTREE_DB_USER`) and password (`INVENTREE_DB_PASSWORD`). You should ensure they are changed from the default values for added security - - -### Initial Database Setup - -Perform the initial database setup by running the following command: - -```bash -docker compose run inventree-server invoke update -``` - -This command performs the following steps: - -- Ensure required python packages are installed -- Create a new (empty) database -- Perform the required schema updates to create the required database tables -- Update translation files -- Collect all required static files into a directory where they can be served by nginx - -### Create Administrator Account - -If you are creating the initial database, you need to create an admin (superuser) account for the database. Run the command below, and follow the prompts: - -``` -docker compose run inventree-server invoke superuser -``` - -Alternatively, admin account details can be specified in the `.env` file, removing the need for this manual step: - -| Variable | Description | -| --- | --- | -| INVENTREE_ADMIN_USER | Admin account username | -| INVENTREE_ADMIN_PASSWORD | Admin account password | -| INVENTREE_ADMIN_EMAIL | Admin account email address | - -!!! warning "Scrub Account Data" - Ensure that the admin account credentials are removed from the `.env` file after the first run, for security. - -### Start Docker Containers - -Now that the database has been created, migrations applied, and you have created an admin account, we are ready to launch the InvenTree containers: - -``` -docker compose up -d -``` - -This command launches the following containers: - -- `inventree-db` - PostgreSQL database -- `inventree-server` - InvenTree web server -- `inventree-worker` - Background worker -- `inventree-nginx` - Nginx reverse proxy - -!!! success "Up and Running!" - You should now be able to view the InvenTree login screen at [http://localhost:1337](http://localhost:1337) - -## Updating InvenTree - -To update your InvenTree installation to the latest version, follow these steps: - -### Stop Containers - -Stop all running containers as below: - -``` -docker compose down -``` - -### Update Images - -Pull down the latest version of the InvenTree docker image - -``` -docker compose pull -``` - -This ensures that the InvenTree containers will be running the latest version of the InvenTree source code. - -!!! tip "Docker Directory" - All `docker compose` commands must be performed in the same directory as the [docker-compose.yml file](#required-files) - -!!! info "Tagged Version" - If you are targeting a particular "tagged" version of InvenTree, you may wish to edit the `INVENTREE_TAG` variable in the `.env` file before issuing the `docker compose pull` command - -### Update Database - -Run the following command to ensure that the InvenTree database is updated: - -``` -docker compose run inventree-server invoke update -``` - -!!! info "Skip Backup" - By default, the `invoke update` command performs a database backup. To skip this step, add the `--skip-backup` flag - -### Start Containers - -Now restart the docker containers: - -``` -docker compose up -d -``` - -## Data Backup - -Database and media files are stored external to the container, in the volume location specified in the `docker-compose.yml` file. It is strongly recommended that a backup of the files in this volume is performed on a regular basis. - -Read more about [data backup](./backup.md). - -### Exporting Database as JSON - -To export the database to an agnostic JSON file, perform the following command: - -``` -docker compose run inventree-server invoke export-records -f /home/inventree/data/data.json -``` - -This will export database records to the file `data.json` in your mounted volume directory. diff --git a/docs/docs/start/intro.md b/docs/docs/start/intro.md index b8a0d56f6b..da035c2d33 100644 --- a/docs/docs/start/intro.md +++ b/docs/docs/start/intro.md @@ -2,71 +2,78 @@ title: Setup Introduction --- -!!! info "Fast install" - A quick-and-easy install can be done done with the following one-liner. - ```bash - wget -qO install.sh https://get.inventree.org && bash install.sh - ``` - Read more about the [installer](./installer.md). - ## Introduction -InvenTree can be self-hosted with minimal system requirements. Multiple database back-ends are supported, allowing for flexibility where required. +A functional InvenTree server can be hosted with minimal setup requirements. Multiple installation methods and database back-ends are supported, allowing for flexibility where required. + +!!! info "Production Ready" + InvenTree is designed to be a production-ready application, and can be deployed in a variety of environments. The following instructions are designed to help you get started with a *production* setup. For a development setup, refer to the [development setup guide](../develop/starting.md). + +## Installation Methods + +To quickly jump to a specific installation method, refer to the following links: + +- [**Docker**](./docker.md) +- [**Package Installer**](./installer.md) +- [**Bare Metal**](./install.md) + +!!! success "Docker Recommended" + The recommended method of installing InvenTree is to follow our [docker setup guide](./docker.md). InvenTree provides out-of-the-box support for docker and docker compose, which provides a simple, reliable and repeatable pipeline for integration into your production environment. + +!!! info "Further Reading" + For more information on the InvenTree tech stack, continue reading below! + +### Configuration Options + +Independent of the preferred installation method, InvenTree provides a number of [configuration options](./config.md) which can be used to customize the server environment. + +## System Components The InvenTree server ecosystem consists of the following components: ### Database -A persistent database is required for data storage. InvenTree can be used with any of the following database backends: +A persistent database is required for data storage. By default, InvenTree is configured to use [PostgreSQL](https://www.postgresql.org/) - and this is the recommended database backend to use. However, InvenTree can also be configured to connect to any database backend [supported by Django]({% include "django.html" %}/ref/databases/) -* PostgreSQL -* MySQL / MariaDB -* SQLite - -!!! warning "SQLite" - While SQLite provides a simpler setup and is useful for a development environment, we strongly recommend against using it for a production environment. Use PostgreSQL or MySQL instead - -Database selection should be determined by your particular installation requirements. - -### Media Files - -Uploaded media files (images, attachments, reports, etc) are stored to a persistent storage volume. ### Web Server -The bulk of the InvenTree code base supports the custom web server application. The web server application services user requests and facilitates database access. +The bulk of the InvenTree code base supports the custom web server application. The web server application services user requests and facilitates database access. The webserver provides access to the [API](../api/api.md) for performing database query actions. -The webserver code also provides a first-party API for performing database query actions. - -Once a database is setup, you need a way of accessing the data. InvenTree provides a "server" application out of the box, but this may not scale particularly well with multiple users. Instead, InvenTree can be served using a webserver such as [Gunicorn](https://gunicorn.org/). For more information see the [deployment documentation](./bare_prod.md). +InvenTree uses [Gunicorn](https://gunicorn.org/) as the web server - a Python WSGI HTTP server. ### Background Tasks -A separate application handles management of [background tasks](../settings/tasks.md), separate to user-facing web requests. +A separate application handles management of [background tasks](../settings/tasks.md), separate to user-facing web requests. The background task manager is required to perform asynchronous tasks, such as sending emails, generating reports, and other long-running tasks. + +InvenTree uses [django-q2](https://django-q2.readthedocs.io/en/master/) as the background task manager. + +### File Storage + +Uploaded *media* files (images, attachments, reports, etc) and *static* files (javascript, html) are stored to a persistent storage volume. A *file server* is required to serve these files to the user. + +InvenTree uses [Caddy](https://caddyserver.com/) as a file server, which is configured to serve both *static* and *media* files. Additionally, Caddy provides SSL termination and reverse proxy services. ## OS Requirements -The InvenTree documentation assumes that the operating system is a debian based Linux OS. Some installation steps may differ for different systems. +The InvenTree documentation *assumes* that the operating system is a debian based Linux OS. Some installation steps may differ for different systems. !!! warning "Installing on Windows" - Installation on Windows is *not guaranteed* to work (at all). To install on a Windows system, it is highly recommended that you [install WSL](https://docs.microsoft.com/en-us/windows/wsl/install-win10#manual-installation-steps), and then follow installation procedure from within the WSL environment. + To install on a Windows system, you should [install WSL](https://docs.microsoft.com/en-us/windows/wsl/install-win10#manual-installation-steps), and then follow installation procedure from within the WSL environment. !!! success "Docker" - Installation on any OS is simplified by following the [docker setup guide](../docker). + Installation on any OS is simplified by following the [docker setup guide](./docker.md). ## Python Requirements -InvenTree runs on [Python](https://python.org). - -!!! warning "Python Version" - InvenTree requires Python 3.9 (or newer). If your system has an older version of Python installed, you will need to follow the update instructions for your OS. +InvenTree requires a minimum Python version of {{ config.extra.min_python_version}}. If your system has an older version of Python installed, you will need to follow the update instructions for your OS. ### Invoke InvenTree makes use of the [invoke](https://www.pyinvoke.org/) python toolkit for performing various administrative actions. !!! warning "Invoke Version" - InvenTree requires invoke version 2.0.0 or newer. Some platforms may be shipped with older versions of invoke! + InvenTree requires invoke version {{ config.extra.min_invoke_version }} or newer. Some platforms may be shipped with older versions of invoke! !!! tip "Updating Invoke" To update your invoke version, run `pip install -U invoke` @@ -102,15 +109,11 @@ To configure Inventree inside a virtual environment, ``cd`` into the inventree b source env/bin/activate ``` -!!! info "Activate Virtual Environment" - if - ``` - source env/bin/activate - ``` - is not working try - ``` - . env/bin/activate - ``` +Or, if that does not work, try: + +``` +. env/bin/activate +``` This will place the current shell session inside a virtual environment - the terminal should display the ``(env)`` prefix. @@ -127,31 +130,10 @@ Alternatively, the source can be downloaded as a [.zip archive](https://github.c !!! info "Updating via Git" Downloading the source code using Git is recommended, as it allows for simple updates when a new version of InvenTree is released. -## Installation Guides - -There are multiple ways to get an InvenTree server up and running, of various complexity (and robustness)! - -### Docker - -The recommended method of installing InvenTree is to use [docker](https://www.docker.com). InvenTree provides out-of-the-box support for docker and docker compose, which provides a simple, reliable and repeatable pipeline for integration into your production environment. - -Refer to the following guides for further instructions: - -- [**Docker development server setup guide**](./docker_dev.md) -- [**Docker production server setup guide**](./docker.md) - -### Bare Metal - -If you do not wish to use the docker container, you will need to manually install the required packages and follow through the installation guide. - -Refer to the following guides for further instructions: - -- [**Bare metal development server setup guide**](./bare_dev.md) -- [**Bare metal production server setup guide**](./install.md) ## Debug Mode -By default, the InvenTree web server is configured to run in [DEBUG mode](https://docs.djangoproject.com/en/dev/ref/settings/#std:setting-DEBUG). +By default, a production InvenTree installation is configured to run with [DEBUG mode]({% include "django.html" %}/ref/settings/#std:setting-DEBUG) *disabled*. Running in DEBUG mode provides many handy development features, however it is strongly recommended *NOT* to run in DEBUG mode in a production environment. This recommendation is made because DEBUG mode leaks a lot of information about your installation and may pose a security risk. diff --git a/docs/docs/start/serving_files.md b/docs/docs/start/serving_files.md index 0d9b5a493a..a641abda09 100644 --- a/docs/docs/start/serving_files.md +++ b/docs/docs/start/serving_files.md @@ -4,25 +4,26 @@ title: Serving Static and Media Files ## Serving Files -In production, the InvenTree web server software *does not* provide hosting of static files, or user-uploaded (media) files. +In a production installation, the InvenTree web server application *does not* provide hosting of static files, or user-uploaded (media) files. Instead, these files should be served by a separate web server, such as [Caddy](https://caddyserver.com/), [Nginx](https://www.nginx.com/), or [Apache](https://httpd.apache.org/). -When running in [production mode](./bare_prod.md) (i.e. the `INVENTREE_DEBUG` flag is disabled), a separate web server is required for serving *static* and *media* files. In `DEBUG` mode, the django webserver facilitates delivery of *static* and *media* files, but this is explicitly not suitable for a production environment. +!!! info "Debug Mode" + When running in [production mode](./bare_prod.md) (i.e. the `INVENTREE_DEBUG` flag is disabled), a separate web server is required for serving *static* and *media* files. In `DEBUG` mode, the django webserver facilitates delivery of *static* and *media* files, but this is explicitly not suitable for a production environment. -!!! into "Read More" - You can find further information in the [django documentation](https://docs.djangoproject.com/en/dev/howto/static-files/deployment/). +!!! tip "Read More" + You can find further information in the [django documentation]({% include "django.html" %}/howto/static-files/deployment/). There are *many* different ways that a sysadmin might wish to handle this - and it depends on your particular installation requirements. -The [docker production example](./docker_prod.md) provides an example using [Nginx](https://www.nginx.com/) to serve *static* and *media* files, and redirecting other requests to the InvenTree web server itself. - -You may use this as a jumping off point, or use an entirely different server setup. - -#### Static Files +### Static Files Static files can be served without any need for authentication. In fact, they must be accessible *without* authentication, otherwise the unauthenticated views (such as the login screen) will not function correctly. -#### Media Files +### Media Files -It is highly recommended that the *media* files are served in such a way that user authentication is required. +It is highly recommended that the *media* files are served behind an authentication layer. This is because the media files are user-uploaded, and may contain sensitive information. Most modern web servers provide a way to serve files behind an authentication layer. -Refer to the [docker production example](./docker_prod.md) for a demonstration of using nginx to serve media files only to authenticated users, and forward authentication requests to the InvenTree web server. +### Example Configuration + +The [docker production example](./docker.md) provides an example using [Caddy](https://caddyserver.com) to serve *static* and *media* files, and redirecting other requests to the InvenTree web server itself. + +Caddy is a modern web server which is easy to configure and provides a number of useful features, including automatic SSL certificate generation. diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml index efdecacad3..848788aaad 100644 --- a/docs/mkdocs.yml +++ b/docs/mkdocs.yml @@ -8,6 +8,7 @@ site_author: InvenTree repo_url: https://github.com/inventree/inventree repo_name: inventree/inventree + # Theme theme: name: material @@ -34,6 +35,7 @@ theme: icon: repo: fontawesome/brands/github features: + - content.code.copy - header.autohide - navigation.expand - navigation.footer @@ -78,7 +80,7 @@ nav: - Getting started: develop/starting.md - Contributing: develop/contributing.md - Devcontainer: develop/devcontainer.md - - Platform UI: develop/react-frontend.md + - React Frontend: develop/react-frontend.md - Credits: credits.md - Privacy: privacy.md - Release Notes: releases/release_notes.md @@ -87,8 +89,7 @@ nav: - Configuration: start/config.md - Docker: - Introduction: start/docker.md - - Production: start/docker_prod.md - - Development: start/docker_dev.md + - Installation: start/docker_install.md - Bare Metal: - Introduction: start/install.md - Installer: start/installer.md @@ -274,6 +275,10 @@ extra: # provider: google # property: UA-143467500-1 + min_python_version: 3.9 + min_invoke_version: 2.0.0 + django_version: 4.2 + version: default: stable provider: mike diff --git a/docs/mlc_config.json b/docs/mlc_config.json new file mode 100644 index 0000000000..1a1cf8b46f --- /dev/null +++ b/docs/mlc_config.json @@ -0,0 +1,13 @@ +{ + "ignorePatterns": [ + { + "pattern": "http://inventree.localhost" + }, + { + "pattern": "http://localhost" + }, + { + "pattern": "http://127.0.0.1" + } + ] +} diff --git a/requirements.in b/requirements.in index db429e2fe7..05033758e8 100644 --- a/requirements.in +++ b/requirements.in @@ -45,7 +45,7 @@ python-barcode[images] # Barcode generator python-dotenv # Environment variable management pyyaml>=6.0.1 # YAML parsing qrcode[pil] # QR code generator -rapidfuzz==0.7.6 # Fuzzy string matching +rapidfuzz # Fuzzy string matching regex # Advanced regular expressions sentry-sdk # Error reporting (optional) setuptools # Standard dependency diff --git a/requirements.txt b/requirements.txt index ac79460982..5ef46e3ce6 100644 --- a/requirements.txt +++ b/requirements.txt @@ -274,7 +274,7 @@ pyyaml==6.0.1 # tablib qrcode==7.4.2 # via django-allauth-2fa -rapidfuzz==0.7.6 +rapidfuzz==3.6.1 redis==5.0.1 # via django-redis referencing==0.33.0 diff --git a/tasks.py b/tasks.py index e7d09d1605..dca41d4755 100644 --- a/tasks.py +++ b/tasks.py @@ -207,8 +207,8 @@ def check_file_existance(filename: str, overwrite: bool = False): # Install tasks -@task(help={'nouv': 'Do not use UV'}) -def plugins(c, nouv=False): +@task(help={'uv': 'Use UV (experimental package manager)'}) +def plugins(c, uv=False): """Installs all plugins as specified in 'plugins.txt'.""" from InvenTree.InvenTree.config import get_plugin_file @@ -217,20 +217,20 @@ def plugins(c, nouv=False): print(f"Installing plugin packages from '{plugin_file}'") # Install the plugins - if nouv: + if not uv: c.run(f"pip3 install --disable-pip-version-check -U -r '{plugin_file}'") else: c.run('pip3 install --no-cache-dir --disable-pip-version-check uv') c.run(f"uv pip install -r '{plugin_file}'") -@task(post=[plugins], help={'nouv': 'Do not use UV'}) -def install(c, nouv=False): +@task(help={'uv': 'Use UV package manager (experimental)'}) +def install(c, uv=False): """Installs required python packages.""" print("Installing required python packages from 'requirements.txt'") # Install required Python packages with PIP - if nouv: + if not uv: c.run('pip3 install --upgrade pip') c.run('pip3 install --upgrade setuptools') c.run( @@ -241,6 +241,9 @@ def install(c, nouv=False): c.run('uv pip install --upgrade setuptools') c.run('uv pip install -U -r requirements.txt') + # Run plugins install + plugins(c, uv=uv) + @task(help={'tests': 'Set up test dataset at the end'}) def setup_dev(c, tests=False): @@ -305,7 +308,7 @@ def static(c, frontend=False): frontend_build(c) print('Collecting static files...') - manage(c, 'collectstatic --no-input --clear') + manage(c, 'collectstatic --no-input --clear --verbosity 0') @task @@ -389,6 +392,7 @@ def migrate(c): 'frontend': 'Force frontend compilation/download step (ignores INVENTREE_DOCKER)', 'no_frontend': 'Skip frontend compilation/download step', 'skip_static': 'Skip static file collection step', + 'uv': 'Use UV (experimental package manager)', }, ) def update( @@ -397,6 +401,7 @@ def update( frontend: bool = False, no_frontend: bool = False, skip_static: bool = False, + uv: bool = False, ): """Update InvenTree installation. @@ -414,7 +419,7 @@ def update( - translate_stats """ # Ensure required components are installed - install(c) + install(c, uv=uv) if not skip_backup: backup(c)