From 0eb2697fe3a6f37924deea13d0fa902abe7e019b Mon Sep 17 00:00:00 2001 From: Oliver Walters Date: Sun, 16 Apr 2023 21:10:42 +1000 Subject: [PATCH 1/2] Adds new page regarding serving static and media files --- docs/start/serving_files.md | 6 ++++++ mkdocs.yml | 1 + 2 files changed, 7 insertions(+) create mode 100644 docs/start/serving_files.md diff --git a/docs/start/serving_files.md b/docs/start/serving_files.md new file mode 100644 index 0000000..f8aa7ec --- /dev/null +++ b/docs/start/serving_files.md @@ -0,0 +1,6 @@ +--- +title: Serving Static and Media Files +--- + +## Serving Files + diff --git a/mkdocs.yml b/mkdocs.yml index c4b7472..74db35d 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -72,6 +72,7 @@ nav: - Installer: start/installer.md - Development: start/development.md - Production: start/production.md + - Serving Files: start/serving_files.md - Data Backup: start/backup.md - Migrating Data: start/migrate.md - Parts: From a8a0796c9f8aa9c3eac08930736fadc5bfb576ff Mon Sep 17 00:00:00 2001 From: Oliver Walters Date: Sun, 16 Apr 2023 21:25:58 +1000 Subject: [PATCH 2/2] Updated doc links --- docs/start/config.md | 3 +++ docs/start/docker_prod.md | 4 ++-- docs/start/install.md | 6 ++++++ docs/start/intro.md | 20 +++----------------- docs/start/production.md | 7 +++++++ docs/start/serving_files.md | 22 ++++++++++++++++++++++ 6 files changed, 43 insertions(+), 19 deletions(-) diff --git a/docs/start/config.md b/docs/start/config.md index 320c968..e6f4507 100644 --- a/docs/start/config.md +++ b/docs/start/config.md @@ -186,6 +186,9 @@ InvenTree requires some external directories for storing files: | INVENTREE_MEDIA_ROOT | media_root | Allow all remote URLS for CORS checks | *Not specified* | | INVENTREE_BACKUP_DIR | backup_dir | List of whitelisted CORS URLs | *Not specified* | +!!! tip "Serving Files" + Read the [Serving Files](./serving_files.md) section for more information on hosting *static* and *media* files + ### Static File Storage Static files **require** a local directory for storage. This directory should be specified with the `static_root` option in the config file based on the particular installation requirements. diff --git a/docs/start/docker_prod.md b/docs/start/docker_prod.md index d3d449c..0d4fe2f 100644 --- a/docs/start/docker_prod.md +++ b/docs/start/docker_prod.md @@ -32,8 +32,8 @@ A sample [docker compose file](https://github.com/inventree/InvenTree/blob/maste 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. -!!! warning "Debug Warning" - When running with `debug=False`, django *will not serve static and media files* - refer to the [django documentation](https://docs.djangoproject.com/en/dev/howto/static-files/). +!!! info "Read More" + Refer to the [Serving Files](./serving_files.md) section for more details #### Required Files diff --git a/docs/start/install.md b/docs/start/install.md index d14d61e..65ba4e3 100644 --- a/docs/start/install.md +++ b/docs/start/install.md @@ -65,10 +65,16 @@ In addition to the location where the InvenTree source code is located, you will InvenTree requires a directory for storage of [static files](./config.md#static-file-storage). +!!! info "Read More" + Refer to the [Serving Files](./serving_files.md) section for more details + #### Media Files InvenTree requires a directory for storage of [user uploaded files](./config.md#uploaded-file-storage) +!!! info "Read More" + Refer to the [Serving Files](./serving_files.md) section for more details + #### Backup Directory Location for storing [database backups](./config.md#backup-file-storage) diff --git a/docs/start/intro.md b/docs/start/intro.md index 8a75af1..83ac5c0 100644 --- a/docs/start/intro.md +++ b/docs/start/intro.md @@ -156,22 +156,8 @@ So, for a production setup, you should set `INVENTREE_DEBUG=false` in the [confi ### Potential Issues -However, turning off DEBUG mode creates further work for the system administrator. In particular, when running in DEBUG mode, the InvenTree web server natively manages *static* and *media* files, which means that the InvenTree server can run "monolithically" without the need for a separate web server. +Turning off DEBUG mode creates further work for the system administrator. In particular, when running in DEBUG mode, the InvenTree web server natively manages *static* and *media* files, which means that the InvenTree server can run "monolithically" without the need for a separate web server. -With DEBUG mode turned off, a separate web server is required for serving *static* and *media* files. You can find further information in the [django documentation](https://docs.djangoproject.com/en/dev/howto/static-files/deployment/). +!!! info "Read More" + Refer to the [Serving Files](./serving_files.md) section for more details -There are *many* different ways that a sysadmin might wish to handle this. - -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 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 - -It is highly recommended that the *media* files are served in such a way that user authentication is required. - -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. diff --git a/docs/start/production.md b/docs/start/production.md index 29b650b..192bac4 100644 --- a/docs/start/production.md +++ b/docs/start/production.md @@ -93,6 +93,13 @@ The process status can be viewed [in your web browser](http://localhost:9001). The InvenTree server (and background task manager) should now be running! +### Static and Media Files + +In addition to the InvenTree server, you will need a method of delivering static and media files (this is *not* handled by the InvenTree server in a production environment). + +!!! info "Read More" + Refer to the [Serving Files](./serving_files.md) section for more details + ### 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/). diff --git a/docs/start/serving_files.md b/docs/start/serving_files.md index f8aa7ec..c73ff3e 100644 --- a/docs/start/serving_files.md +++ b/docs/start/serving_files.md @@ -4,3 +4,25 @@ 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. + +When running in [production mode](./production.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/). + +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 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 + +It is highly recommended that the *media* files are served in such a way that user authentication is required. + +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.