# clients/android.md
# Android
A Native Android Application is Available.
[[toc]]
::: danger :rotating_light: **Free and Open-Source Android is under threat!**
Google will turn Android into a locked-down platform, restricting your essential freedom to install apps of your choice. Make your voice heard β [Keep Android Open](https://keepandroidopen.org/).
:::
## Install
Get it from GitHub or Obtainium.
[](https://github.com/django-files/android-client/releases/latest/download/app-release.apk)
[](https://apps.obtainium.imranr.dev/redirect?r=obtainium://add/https://github.com/django-files/android-client)
::: details View QR Codes πΈ
[](https://github.com/django-files/android-client/releases/latest/download/app-release.apk)
[](https://apps.obtainium.imranr.dev/redirect?r=obtainium://add/https://github.com/django-files/android-client)
:::
_Note: Google Play is currently in closed testing._
_The GitHub APK has been registered with Google's [Android developer verification](https://developer.android.com/developer-verification)._
```
A0:11:F5:75:CA:69:54:E4:0A:97:A0:C9:85:AC:35:FB:99:3F:DA:73:37:0B:97:EA:23:7D:02:F1:0A:41:2F:D0
```
[_How to Verify an APK Signature_](https://developer.android.com/tools/apksigner#usage-verify)
## Setup
Navigate to: `User Settings` > `Clients`
Click on the `View QR Authentication Code` button.
1. If you are on your phone, click on the QR.
2. If on a computer, scan the QR code with your phone.
Click `Add Server` and you are done!
## Features
- Share or Open any file(s) and automatically copy the URL to the clipboard.
- Upload Previews for single media and scrolling selection for multiple files.
- Native File List with Options, Infinite Scroll, and Multi-Select Options.
- Supports Native Local Login, GitHub OAuth, Google OAuth, and Discord OAuth.
- Ability to add multiple servers and switch on the fly from the Server List menu.
- Widget with Stats, Upload Shortcut, Custom Background Update Interval, and More.
- Automatic Authentication from Authenticated Sessions with QR Code or Deep Link.
> [!INFO]
> Missing a feature? Submit a [Feature Request](https://github.com/django-files/android-client/discussions/categories/feature-requests)!
## Screenshots
---
# clients/browser.md
# Browser Addon
A Web Extension is available for all major browsers including Firefox Android.
[[toc]]
## Install
Get it from Google or Mozilla.
- [Chrome Web Store](https://chromewebstore.google.com/detail/django-files/abpbiefojfkekhkjnpakpekkpeibnjej)
- [Mozilla Addons](https://addons.mozilla.org/addon/django-files)
::: details View QR Codes πΈ
Mozilla Firefox Android
[](https://addons.mozilla.org/firefox/addon/django-files)
Chrome Web Store
[](https://chromewebstore.google.com/detail/django-files/abpbiefojfkekhkjnpakpekkpeibnjej)
:::
## Setup
To configure, navigate to your Django Files site, and activate the extension popup.
Click `Authorize Server` and you are done!
Alternatively you can copy and paste your URL and Token into the Settings.
## Features
- View Recent Uploads on Popup
- Preview Popup Images on Hover
- Drag and Drop files to the Popup or Sidepanel
- Right Click any Image, Video, or Audio to Upload
- Right Click any URL to Shorten
- Automatically Auth with Django Files
> [!INFO]
> Missing a feature? Submit a [Feature Request](https://github.com/django-files/web-extension/discussions/categories/feature-requests)!
## Screenshots
::: tip Upload w/ Native ShareX Client
If you are only uploading images and want to use your locally installed ShareX for processing, ShareX now supports native messaging.
Download [ShareX](https://getsharex.com/) for [Chrome](https://chromewebstore.google.com/detail/sharex/nlkoigbdolhchiicbonbihbphgamnaoc)
or [Firefox](https://addons.mozilla.org/en-US/firefox/addon/sharex/).
:::
---
# clients/cli.md
# Command Line Interface
A CLI is available for Python 3 from [PyPi](https://pypi.org/project/zipline-cli).
[[toc]]
::: warning New ShareX CLI Available
A new CLI is available and supports any ShareX server.
For more details visit:
Additionally, this is being re-written in GoLang to remove the Python dependency.
:::
## Install
The easiest way to install is with `pip`.
```shell
python -m pip install zipline-cli
```
Alternatively, you can install from source.
```shell
git clone https://github.com/cssnr/zipline-cli.git
python3 -m pip install -e zipline-cli
```
## Setup
To configure the CLI run the `setup` command.
```shell
zipline-cli setup
```
This will interactively prompt you for server details and store them in your home directory.
---
# clients/flameshot.md
# Flameshot
For Linux, you should use the [Flameshot](https://flameshot.org/) client.
[[toc]]
## Setup
Navigate to: `User Settings` > `Clients`
Click on the Flameshot Script icon to download the `.sh` file.
This script contains your token, save it somewhere securely on the system.
The script launches flameshot and uploads the resulting file to the server.
> [!IMPORTANT]
> The script uses `curl` to upload the file which must be installed.
---
# clients/index.md
# Clients
Many [Popular](#popular) clients are supported, including [Native](#native) clients for Mobile and others.
## Popular
Popular upload clients with one-click configuration:
- [ShareX](sharex.md)
- [Flameshot](flameshot.md)
- [Shortcuts](shortcuts.md)
## Native
Clients made by [django-files](https://github.com/django-files) to work with [django-files](https://github.com/django-files/django-files):
- [iOS](ios.md)
- [Android](android.md)
- [Web Browser Addon](browser.md)
- [Command Line Interface](cli.md)
---
# clients/ios.md
# iOS
Your Django Files instance is easy to use from your iOS device with our native client.
[[toc]]
## Install
Download on the Apple App Store.
[](https://apps.apple.com/us/app/django-files/id6742523003)
[](https://apps.apple.com/us/app/django-files/id6742523003)
## Setup
The fastest way to add your server is via QR code from the web UI:
1. In a browser, navigate to your Django Files site and go to **User Settings** > **Clients**.
2. Click **View QR Authentication Code**.
- On your iPhone: tap the QR code β it will open the app and add the server automatically.
- On a computer: scan the QR code with your iPhone camera.
3. Tap **Add Server** β done!
## Features
- Share any file (or multiple) from the iOS share sheet and automatically copy the URL to clipboard.
- Add multiple servers and switch between them from the server list.
- Upload directly from your camera or stream your screen/camera live via RTMP.
- Deep links from the web UI open files, albums, and streams directly in the app.
- Fully native iOS UI.
> [!INFO]
> Missing a feature? Submit a [Feature Request](https://github.com/django-files/ios-client/discussions/categories/feature-requests)!
---
# clients/sharex.md
# ShareX
For Windows, you should use the [ShareX](https://getsharex.com/) client.
[[toc]]
## Setup
Navigate to: `User Settings` > `Clients`
Click on the ShareX Files or URL Shorts icon to download the `.sxcu` file.
This file should open with ShareX.
If not go to: `Destinations` > `Custom uploader settings` > `Import`
Then select the downloaded `.sxcu` file.
---
# clients/shortcuts.md
# Shortcuts
For macOS, you should use [Shortcuts](https://support.apple.com/guide/shortcuts-mac/welcome/mac).
Additionally, [Shortcuts](https://support.apple.com/guide/shortcuts/welcome/ios) is available for iOS.
[[toc]]
## Setup
Get started by getting the [shortcut](https://www.icloud.com/shortcuts/9fde67b3aa9c401b86987061e5c359a8).
[](https://www.icloud.com/shortcuts/9fde67b3aa9c401b86987061e5c359a8)
> [!TIP]
> Shortcuts will eventually be replaced by the [iOS Client](ios.md).
---
# docs/index.md
# Documentation
> [!WARNING]
> The Documentation is a Work in Progress and may be incomplete.
For more details see the [README.md](https://github.com/django-files/django-files?tab=readme-ov-file#readme) on GitHub.
---
# guides/features.md
# Features
Django Files is packed with features for seamless file management and sharing.
More features are in progress!
[[toc]]
> [!INFO]
> Missing a feature? Submit a [Feature Request](https://github.com/django-files/django-files/discussions/categories/feature-requests)!
## Screenshots
## Core Features
- Local or S3 storage support
- One-click integration with ShareX, Flameshot
- [iOS Client](../clients/ios.md)
- [Android Client](../clients/android.md)
- Organize with tags β on files, albums, and streams, searchable everywhere
- Customizable UI with light/dark mode
- OAuth support (Discord, GitHub, Google) & two-factor authentication (Duo)
- [Webhooks](webhooks.md) β event notifications to Discord or any custom endpoint, with per-tag filtering
- [Web Extensions](../clients/browser.md) for Chrome and Firefox
- Public upload support (optional)
## Authentication & Security
- Multi-user support with local & OAuth authentication options
- Invite system for user onboarding
- OAuth configuration via Django Admin (no restart required)
## UI & File Management
- Drag & Drop file uploads
- Short URLs with vanity support
- Private & password-protected files
- Configurable EXIF metadata removal on upload
- Bulk file actions
- Albums & galleries for organizing files
## Stats & Insights
- Dashboard with user-friendly overview & stats
- Graph-based analytics (work in progress)
- File expiration & view counting
## Live Streaming
- RTMP ingest with HLS playback via Video.js
- Live/offline status badge and real-time viewer count
- Push notification subscriber count
- Stream title and description β editable in-place by the stream owner
- Webhook notifications on stream start/end β Discord or any custom endpoint
- See the [Live Streaming guide](streaming.md) for setup details
### Live Chat
- Real-time WebSocket chat with message history on join
- Viewer list with avatars
- Color-coded usernames; stream owner messages highlighted distinctly
- Notification sound toggle (persisted per browser)
- Owner controls: enable/disable live chat and anonymous chat without stopping the stream
- Ban system to remove disruptive viewers
### Chat Slash Commands
Type `/` in the chat input to see available commands with autocomplete (Tab and arrow key navigation).
**All viewers:**
| Command | Description |
| ------------------ | --------------------------------------------- |
| `/set-name ` | Set a custom display name (max 32 characters) |
| `/leave` | Disconnect from chat |
| `/join` | Rejoin chat after leaving |
| `/notify` | Toggle notification sound on/off |
**Stream owner only:**
| Command | Description |
| ------------------------------------- | -------------------------------------- |
| `/title ` | Update the stream title live |
| `/description <text>` | Update the stream description live |
| `/ban <display_name>` | Ban a viewer from chat |
| `/ban-message-cleanup <display_name>` | Ban a viewer and remove their messages |
---
# guides/get-started.md
# Getting Started
Get started by [running](#running) the server on your host and [accessing](#accessing) the site.
You can also view the π οΈ [Features](features.md) and πΈ [Screenshots](features.md#screenshots).
## Running
The fastest way to get up and running is with [Docker](https://www.docker.com/).
::: code-group
```shell [Docker Compose]
version: '3'
services:
django-files:
image: ghcr.io/django-files/django-files:latest
environment:
USERNAME: "myadminuser"
PASSWORD: "pleasechangeme"
volumes:
- media_dir:/data/media
ports:
- "80:80"
- "1935:1935" # RTMP β remove if not using live streaming
volumes:
media_dir:
```
```shell [Docker CLI]
docker run --name "django-files" -d --restart unless-stopped \
-p 80:80 -p 1935:1935 \
-v /data/django-files:/data/media \
-e USERNAME=myadminuser \
-e PASSWORD=pleasechangeme \
ghcr.io/django-files/django-files:latest
```
:::
> [!NOTE]
> **Live streaming requires port 1935 (RTMP) to be reachable by your streaming client.**
> The container always listens on `1935` internally β you can publish it on any available host port (e.g. `1936:1935`).
> If your server is behind a router or firewall you must forward that port to the host.
> Cloud VMs (AWS, GCP, etc.) also need an inbound rule in their security group / firewall policy.
> See the [Live Streaming guide](streaming.md) for full setup details including the `RTMP_HOST` variable.
_Note: you can run from source; however, this is currently not documented or supported._
## Accessing
Once the server is up and running you can access the site from a web browser.
If running on your localhost with default port mapping, you can access it here:
- http://localhost/
If you set a `USERNAME` or `PASSWORD` environment variable, use those values.
Otherwise, the default credentials are.
| Default | Value |
| ------------ | -------------- |
| **username** | `admin` <CB /> |
| **password** | `12345` <CB /> |
Next you can review the [server setup](setup.md) and start [uploading](upload.md) or check out the [features](features.md).
---
# guides/setup.md
# Server Setup
This section covers server configuration.
[[toc]]
## Storage
The directory mounted to `/data/media` has the following structure.
| Directory | Description |
| --------- | ------------------------------------------------- |
| `db` | If using SQLite the database file is stored here. |
| `files` | If using file storage, the files are stored here. |
| `redis` | Redis snapshots are stored here. |
## Database
By default `sqlite3` is used and provisioned automatically.
You can choose another database, but you must configure it yourself.
Supported Database Backends:
- sqlite3
- mysql
- postgresql
To configure a database use the following variables.
| Variable | Description |
| ------------- | ------------------------------------ |
| DATABASE_TYPE | `sqlite3` or `mysql` or `postgresql` |
| DATABASE_NAME | Database name |
| DATABASE_USER | Database username |
| DATABASE_PASS | Database password |
| DATABASE_HOST | Database hostname |
| DATABASE_PORT | Optional if default |
## Variables
> [!WARNING]
> All variables are optional. This is for reference only.
| Variable | Description | Example |
| ------------------------- | ----------------------------------------- | -------------------------------------- |
| SECRET | App Secret | `JYGTKLztZxVdu5NXuhXGhFJ4AHrJ5YHigQqq` |
| SITE_URL | Site URL | `https://example.com` |
| USERNAME | Local Username | `admin` |
| PASSWORD | Local Password | `PSZX7TgiSg6aB6sZ` |
| SUPER_USERS | oAuth Sup User IDs | `111150265075298304,11114800698361444` |
| DISCORD_CLIENT_ID | Discord Client ID | `1135676900124135484` |
| DISCORD_CLIENT_SECRET | Discord Secret | `HbSyPWgOBx1U38MqmEEUy75KUe1Pm7dR` |
| GITHUB_CLIENT_ID | GitHub Client ID | `1135676900124135484` |
| GITHUB_CLIENT_SECRET | GitHub Secret | `HbSyPWgOBx1U38MqmEEUy75KUe1Pm7dR` |
| GOOGLE_CLIENT_ID | Google Client ID | `123-asdf.apps.googleusercontent.com` |
| GOOGLE_CLIENT_SECRET | Google Secret | `GCSDPC-Tskdfix-klsjdf_r32489fj09jfsd` |
| OAUTH_REDIRECT_URL | Discord Redirect | `https://example.com/oauth/callback/` |
| AWS_REGION_NAME | AWS Region Name | `us-east-1` |
| AWS_ACCESS_KEY_ID | AWS IAM User Key | `AKIEAKADFGASDFASGSDAFSDF` |
| AWS_SECRET_ACCESS_KEY | AWS IAM Secret | `eVJsrhftrv2fcwyYcy323Sfhe5svy5436r55` |
| AWS_STORAGE_BUCKET_NAME | Name of s3 bucket | `my-s3-bucket` |
| STATIC_QUERYSTRING_EXPIRE | static link expire | `300` |
| AWS_S3_CDN_URL | proxy or cdn url | `https://examples3cdndomain.com` |
| DUO_API_HOST | DUO API Host | `api-abc123.duosecurity.com` |
| DUO_CLIENT_ID | DUO Client ID | `nmoNmuLM72WB3RsNkwuv` |
| DUO_CLIENT_SECRET | DUO Secret | `nmoNmuLM72WB3RsNkwuvnmoNuLM72WB3RsNk` |
| SENTRY_URL | Sentry URL | `https://abc@123.ingest.sentry.io/123` |
| SENTRY_ENVIRONMENT | Sentry ENV | `prod` |
| RTMP_HOST | RTMP hostname override for URL generation | `my-df-server.example.com` |
## Live Streaming
RTMP is built in and enabled by default. Port `1935` must be exposed and reachable β see the [Live Streaming guide](streaming.md) for OBS setup, optional URL parameters, and NAT/firewall notes.
`RTMP_HOST` overrides the hostname used when generating RTMP URLs in the UI. Set this when your server is behind a CDN or reverse proxy where the auto-detected hostname would be wrong β otherwise streaming clients will receive incorrect URLs.
---
# guides/streaming.md
# Live Streaming (RTMP)
Django Files includes a built-in RTMP server for live streaming via HLS.
[[toc]]
## Prerequisites
The container's RTMP server always listens on port `1935` internally. You must publish it to a host port so your streaming client can reach it. Docker port mappings are `HOST_PORT:CONTAINER_PORT` β you can use any available host port if `1935` is already in use on your machine (e.g. `1936:1935`).
::: code-group
```yaml [Docker Compose]
services:
django-files:
image: ghcr.io/django-files/django-files:latest
ports:
- '80:80'
- '1935:1935' # host port : container port β change the left value if needed
volumes:
- media_dir:/data/media
```
```shell [Docker CLI]
docker run --name "django-files" -d --restart unless-stopped \
-p 80:80 -p 1935:1935 \
-v /data/django-files:/data/media \
-e USERNAME=myadminuser \
-e PASSWORD=pleasechangeme \
ghcr.io/django-files/django-files:latest
```
:::
> [!WARNING]
> If your server is behind a router, NAT, or cloud firewall (AWS security groups, GCP firewall rules, etc.), you must allow inbound TCP on the host port you chose. RTMP is **not** HTTP β it will not pass through a standard reverse proxy or CDN.
>
> If the auto-detected hostname is wrong (e.g. behind a CDN), set `RTMP_HOST` to a direct hostname so the UI generates correct RTMP URLs for streaming clients. See [Custom RTMP Host](#custom-rtmp-host) below.
## OBS Setup
Navigate to **Streams** in the Django Files UI to find your pre-filled Server URL and Stream Key.
Or build them manually:
| Field | Value |
| ---------- | ------------------------------------------------ |
| Service | `Custom...` |
| Server URL | `rtmp://<your-host>/live?token=<your-api-token>` |
| Stream Key | Any name, e.g. `mystream` |
Your **API token** is shown in your user settings page.
## Optional URL Parameters
Append these to the Server URL to set stream metadata without changing them in the UI each time:
| Parameter | Description | Example |
| -------------- | ---------------------------------- | -------------------------- |
| `title` | Stream title | `title=My+Stream` |
| `description` | Short description | `description=Gaming+night` |
| `public` | Public visibility (`true`/`false`) | `public=false` |
| `viewer_limit` | Max concurrent viewers | `viewer_limit=50` |
Example full URL:
```
rtmp://example.com/live?token=abc123&title=My+Stream&public=true
```
## Custom RTMP Host
The app auto-detects the hostname for RTMP URLs from the request or `SITE_URL`. Set `RTMP_HOST` to override this β required when the auto-detected value would be wrong, such as when behind a CDN or reverse proxy.
| Variable | Description | Example |
| ----------- | ----------------------------------- | -------------------------- |
| `RTMP_HOST` | Hostname used to generate RTMP URLs | `my-df-server.example.com` |
## Watching a Stream
Active streams are listed at `/streams/`. Each stream has a public HLS player at `/live/<stream-name>/`.
The HLS endpoint is also available directly:
```
http://<your-host>/hls/<stream-name>/index.m3u8
```
## Webhook Notifications
Stream start/end notifications can be sent to Discord or any custom endpoint. Subscribe a webhook to the **Stream Live** and **Stream Ended** events under **Settings β Webhooks** β see the [Webhooks guide](webhooks.md) for details.
---
# guides/upload.md
# Uploading
There are more ways to upload than we can keep up withβ¦
[[toc]]
## Website
From the site you can drag and drop any file(s) up upload them.
If you navigate to an album, any files you drop will upload to that album.
## Token
To upload files from elsewhere you will need your Auth Token and Site URL.
From the user menu you can Copy Token or URL.
This is needed to use an upload [Client](#clients).
## Clients
You can download one-click configurations for many clients on the User page.
Navigate to: `User Settings` > `Clients`
There is also a list of [supported clients](../clients/index.md).
---
# guides/webhooks.md
# Webhooks
Django Files can notify other services when things happen on your instance β send rich Discord messages or JSON payloads to any endpoint you control.
[[toc]]
## What You Can Do
- **Discord** β post rich embeds to a channel: image previews, video thumbnails, stream go-live announcements with title/description/duration, all branded with your site name. Add one by pasting a webhook URL, or click **Add Discord Webhook** to pick the channel on Discord itself and finish setup back in Django Files.
- **Custom endpoints** β receive a JSON payload at any HTTP URL. Payloads can be signed with a per-webhook secret (HMAC-SHA256, sent as `X-Webhook-Signature`) so your receiver can verify authenticity.
Webhooks are managed under **Settings β Webhooks**, where you can add, edit, test, and delete them. Each webhook subscribes to exactly the events you choose β and can be narrowed further with tag filters.
## Events
| Event | Fires when |
| --------------------------------- | ----------------------------------------- |
| File Uploaded | A file finishes uploading |
| File Deleted | A file is deleted |
| Album Created / Updated / Deleted | Albums change |
| Short URL Created / Deleted | Short links change |
| Stream Live | A live stream starts |
| Stream Ended | A live stream ends |
| User Login | A user signs in |
| User Created / Deleted | Accounts change (site-wide webhooks only) |
## Tag Filters
Only want to hear about some of your content? Files, albums, and streams can all be tagged in Django Files, and any webhook can be limited to the tags you care about:
- `wallpapers, memes` β only fire for content tagged **wallpapers** or **memes**
- `!private` β fire for everything _except_ content tagged **private**
Set the filter in the webhook editor β events that support tag filtering are marked with a small tag icon. Leave it blank and the webhook fires for everything, same as before.
> [!NOTE]
> Tags aren't just for webhooks: add them from the file preview, album and stream menus, or in bulk from any list view β you can even tag files as you upload them β and search finds your content by tag everywhere.
## Site-Wide Webhooks
Regular webhooks fire for your own activity. Superusers can also create **site-wide webhooks** under **Site Settings β Site Webhooks**, which receive events for every user on the instance β including new account registrations and deletions.
## Payload
Custom webhooks receive a `POST` with a consistent envelope; the `data` object carries the event details:
```json
{
"event": "file.upload",
"timestamp": "2026-07-10T14:32:00+00:00",
"site_url": "https://example.com",
"data": {
"id": 42,
"name": "photo.jpg",
"url": "https://example.com/u/photo.jpg",
"raw_url": "https://example.com/raw/photo.jpg",
"size": 204800,
"mime": "image/jpeg",
"user": "username",
"captured_at": "08/08/2012 16:29:49",
"location": "MΓΊlaΓΎing, Γsland",
"camera": "NIKON CORPORATION NIKON D800E",
"tags": ["travel", "iceland"]
}
}
```
Every request includes an `X-Webhook-Event` header with the event key, and deliveries are retried automatically on failure. Full request/response schemas are documented in the [API reference](https://github.com/django-files/django-files/blob/master/swagger.yaml).
> [!TIP]
> Use the **Test** button next to any webhook to fire a sample event and confirm your endpoint or Discord channel receives it.