Static files ============ To serve static files (i.e., serve arbitrary files from a given directory), the :func:`~litestar.static_files.create_static_files_router` can be used to create a :class:`Router ` to handle this task. .. literalinclude:: /examples/static_files/full_example.py :language: python :caption: Serving static files using :func:`create_static_files_router ` In this example, files from the directory ``assets`` will be served on the path ``/static``. A file ``assets/hello.txt`` would now be available on ``/static/hello.txt`` .. attention:: Directories are interpreted as relative to the working directory from which the application is started Sending files as attachments ---------------------------- By default, files are sent "inline", meaning they will have a ``Content-Disposition: inline`` header. Setting :paramref:`~litestar.static_files.create_static_files_router.params.send_as_attachment` to ``True`` will send them with a ``Content-Disposition: attachment`` instead: .. literalinclude:: /examples/static_files/send_as_attachment.py :language: python :caption: Sending files as attachments using the the :paramref:`~litestar.static_files.create_static_files_router.params.send_as_attachment` parameter of :func:`create_static_files_router` HTML mode --------- "HTML mode" can be enabled by setting :paramref:`~litestar.static_files.create_static_files_router.params.html_mode` to ``True``. This will: - Serve and ``/index.html`` when the path ``/`` is requested - Attempt to serve ``/404.html`` when a requested file is not found .. literalinclude:: /examples/static_files/html_mode.py :language: python :caption: Serving HTML files using the :paramref:`~litestar.static_files.create_static_files_router.params.html_mode` parameter of :func:`create_static_files_router` Passing options to the generated router --------------------------------------- Options available on :class:`~litestar.router.Router` can be passed to directly :func:`~litestar.static_files.create_static_files_router`: .. literalinclude:: /examples/static_files/passing_options.py :language: python :caption: Passing options to the router generated by :func:`create_static_files_router` Using a custom router class --------------------------- The router class used can be customized with the :paramref:`~.static_files.create_static_files_router.params.router_class` parameter: .. literalinclude:: /examples/static_files/custom_router.py :language: python :caption: Using a custom router class with :func:`create_static_files_router` Retrieving paths to static files -------------------------------- :meth:`~litestar.app.Litestar.route_reverse` and :meth:`~litestar.connection.ASGIConnection.url_for` can be used to retrieve the path under which a specific file will be available: .. literalinclude:: /examples/static_files/route_reverse.py :language: python :caption: Retrieving paths to static files using :meth:`~.app.Litestar.route_reverse` .. tip:: The ``name`` parameter has to match the ``name`` parameter passed to :func:`create_static_files_router`, which defaults to ``static``. (Remote) file systems --------------------- To customize how Litestar interacts with the file system, a class implementing the :class:`~litestar.file_system.BaseFileSystem` or any `fsspec `_ file system can be passed to ``file_system``, providing integrations for FTP, SFTP, Hadoop, SMB, GitHub and `many more `_, with support for popular cloud providers available via 3rd party implementations such as - S3 via `S3FS `_ - Google Cloud Storage via `GCSFS `_ - Azure Blob Storage via `adlfs `_ .. literalinclude:: /examples/static_files/file_system.py :language: python :caption: Using a custom file system with :func:`create_static_files_router` Handling symlinks ----------------- Local file systems (e.g. Litestar's :class:`~litestar.file_system.BaseLocalFileSystem` or :class:`fsspec.implementations.local.LocalFileSystem`) may support symlinks, which can cause unexpected behaviour. The ``allow_symlinks_outside_directory`` parameter controls whether symbolic links inside the configured base directories can point to locations outside those directories. By default, this setting is disabled to ensure strict access control and prevent unintended exposure of files outside the specified directories. .. danger:: Keep this option disabled (default) unless absolutely necessary, to prevent accidental exposure of files outside the intended directories. **It should only be enabled in controlled environments where symlink behavior is well understood.** Security considerations ++++++++++++++++++++++++ Enabling this option introduces potential security risks, as it may allow access to files that were not intended to be served. Improperly configured symlinks could allow to traverse directory boundaries and expose sensitive information. This option should only be enabled if all symlinks in the base directory are known and it is ensured that proper file system permissions are in place to prevent unintended exposure. Behavior based on file system support ++++++++++++++++++++++++++++++++++++++ The behavior of ``allow_symlinks_outside_directory`` depends on the underlying file system's symlink capabilities: **File systems that do not support symlinks** If the configured ``file_system`` does not inherit from :class:`LinkableFileSystem`, setting ``allow_symlinks_outside_directory`` to any value other than ``None`` will raise a :exc:`TypeError`. This ensures that unsupported file systems do not inadvertently allow symlink traversal. **File systems that support symlinks** If the file system supports symlinking, the default value is ``False``. This means that, unless explicitly enabled, symlinks will be restricted to paths inside the defined base directories. .. seealso:: :ref:`usage/file_systems:Adapting file systems that support symlinks`