0
# Configuration
1

2
Django Filer provides comprehensive configuration options for storage backends, permissions, validation, upload handling, and admin interface customization. All settings are configured in your Django settings.py file.
3

4
## Capabilities
5

6
### Core Settings
7

8
Basic configuration options that control filer's core behavior and features.
9

10
```python { .api }
11
# Image Model Configuration
12
FILER_IMAGE_MODEL = 'filer.Image'
13
# str: Swappable image model path (default: 'filer.Image')
14
# Allows using custom image models inheriting from BaseImage
15

16
# Permission System
17
FILER_ENABLE_PERMISSIONS = True  
18
# bool: Enable folder-level permissions (default: False)
19
# When enabled, provides granular read/edit/add_children permissions
20

21
# Default Public/Private State
22
FILER_IS_PUBLIC_DEFAULT = True
23
# bool: Default public state for new files (default: True)
24
# Used by is_public_default() function
25

26
# Admin Interface
27
FILER_PAGINATE_BY = 100
28
# int: Number of items per page in admin (default: 100)
29

30
FILER_ADMIN_ICON_SIZES = [
31
    ('16', '16x16'),
32
    ('32', '32x32'), 
33
    ('48', '48x48'),
34
    ('64', '64x64'),
35
]
36
# list: Available icon sizes in admin interface
37

38
FILER_TABLE_ICON_SIZE = 40
39
# int: Icon size for admin table view (default: 40)
40

41
FILER_THUMBNAIL_ICON_SIZE = 120
42
# int: Icon size for admin thumbnail view (default: 120)
43

44
FILER_FOLDER_ADMIN_DEFAULT_LIST_TYPE = 'tb'
45
# str: Default admin list view type ('tb' for table, 'th' for thumbnail)
46

47
# File Model Registry
48
FILER_FILE_MODELS = (
49
    'filer.models.File',
50
    'filer.models.Image',
51
)
52
# tuple: Ordered list of file model classes to check when adding files
53

54
# Debug and Logging
55
FILER_DEBUG = False
56
# bool: Enable debug mode for filer (default: False)
57

58
FILER_ENABLE_LOGGING = False
59
# bool: Enable error logging (default: False)
60
```
61

62
### Storage Configuration
63

64
Configure storage backends for public and private files, including custom storage classes and media serving.
65

66
```python { .api }
67
# Storage Backend Configuration
68
FILER_STORAGES = {
69
    'public': {
70
        'main': {
71
            'ENGINE': 'django.core.files.storage.FileSystemStorage',
72
            'OPTIONS': {
73
                'location': '/path/to/public/media',
74
                'base_url': '/media/filer_public/',
75
            },
76
        },
77
        'thumbnails': {
78
            'ENGINE': 'django.core.files.storage.FileSystemStorage', 
79
            'OPTIONS': {
80
                'location': '/path/to/public/thumbnails',
81
                'base_url': '/media/filer_public_thumbnails/',
82
            },
83
        },
84
    },
85
    'private': {
86
        'main': {
87
            'ENGINE': 'django.core.files.storage.FileSystemStorage',
88
            'OPTIONS': {
89
                'location': '/path/to/private/media',
90
                'base_url': '/smedia/filer_private/',
91
            },
92
        },
93
        'thumbnails': {
94
            'ENGINE': 'django.core.files.storage.FileSystemStorage',
95
            'OPTIONS': {
96
                'location': '/path/to/private/thumbnails', 
97
                'base_url': '/smedia/filer_private_thumbnails/',
98
            },
99
        },
100
    },
101
}
102
# dict: Complete storage configuration for public/private files and thumbnails
103

104
# Legacy Storage Settings (still supported)
105
FILER_PUBLICMEDIA_STORAGE = 'django.core.files.storage.FileSystemStorage'
106
FILER_PUBLICMEDIA_ROOT = '/path/to/public/media'
107
FILER_PUBLICMEDIA_URL = '/media/filer_public/'
108

109
FILER_PRIVATEMEDIA_STORAGE = 'django.core.files.storage.FileSystemStorage'
110
FILER_PRIVATEMEDIA_ROOT = '/path/to/private/media'
111
FILER_PRIVATEMEDIA_URL = '/smedia/filer_private/'
112

113
# Server Configuration for Private Files
114
FILER_SERVERS = {
115
    'private': {
116
        'main': {
117
            'ENGINE': 'filer.server.backends.default.DefaultServer',
118
            'OPTIONS': {},
119
        },
120
        'thumbnails': {
121
            'ENGINE': 'filer.server.backends.default.DefaultServer',
122
            'OPTIONS': {},
123
        },
124
    },
125
}
126
# dict: Server backends for serving private files
127

128
# Available server backends:
129
# - 'filer.server.backends.default.DefaultServer' - Django default
130
# - 'filer.server.backends.nginx.NginxXAccelRedirectServer' - Nginx X-Accel
131
# - 'filer.server.backends.xsendfile.ApacheXSendfileServer' - Apache X-Sendfile
132
```
133

134
### Server Backend Classes
135

136
Available server backend implementations for efficient private file serving.
137

138
```python { .api }
139
# Base Server Backend
140
class ServerBase:
141
    """
142
    Abstract base class for server backends.
143
    
144
    Provides interface for serving private files through
145
    various web server mechanisms.
146
    """
147
    
148
    def serve(self, request, file_obj, **kwargs):
149
        """
150
        Serve a private file through the backend.
151
        
152
        Args:
153
            request: Django HTTP request
154
            file_obj: File object to serve
155
            **kwargs: Additional backend-specific options
156
            
157
        Returns:
158
            HttpResponse: Response for serving the file
159
        """
160

161
# Default Django Server
162
class DefaultServer(ServerBase):
163
    """
164
    Default server backend using Django's static file serving.
165
    
166
    Suitable for development but not recommended for production
167
    as it serves files through Django process.
168
    """
169

170
# Nginx X-Accel-Redirect Server  
171
class NginxXAccelRedirectServer(ServerBase):
172
    """
173
    Nginx X-Accel-Redirect server backend for efficient file serving.
174
    
175
    Uses Nginx's internal redirect mechanism to serve files
176
    without passing through Django process.
177
    
178
    Configuration Options:
179
    - location: File system path prefix
180
    - nginx_location: Nginx internal location prefix
181
    """
182

183
# Apache X-Sendfile Server
184
class ApacheXSendfileServer(ServerBase):
185
    """
186
    Apache X-Sendfile server backend for efficient file serving.
187
    
188
    Uses Apache's X-Sendfile module to serve files efficiently
189
    without loading them into memory.
190
    
191
    Configuration Options:
192
    - sendfile_root: Root directory for sendfile
193
    """
194
```
195

196
### Upload and File Handling
197

198
Settings that control file uploads, processing, and validation.
199

200
```python { .api }
201
# Upload Limits
202
FILER_UPLOADER_CONNECTIONS = 3
203
# int: Maximum simultaneous upload connections (default: 3, 1 for SQLite)
204

205
FILER_UPLOADER_MAX_FILES = 100
206
# int: Maximum number of files per upload session (default: 100)
207

208
FILER_UPLOADER_MAX_FILE_SIZE = 10 * 1024 * 1024  # 10MB
209
# int: Maximum individual file size in bytes (default: 10MB)
210

211
FILER_MAX_IMAGE_PIXELS = None
212
# int or None: Maximum image pixel count for security (default: None)
213

214
FILER_MAX_SVG_THUMBNAIL_SIZE = 1024 * 1024  # 1MB
215
# int: Maximum SVG file size for thumbnail generation (default: 1MB)
216

217
# Filename Generation
218
FILER_FILENAME_GENERATORS = [
219
    'filer.utils.generate_filename.randomized',
220
]
221
# list: Functions for generating upload filenames
222

223
# Canonical URL Settings
224
FILER_CANONICAL_URL = 'canonical/'
225
# str: URL pattern for canonical file URLs (default: 'canonical/')
226
```
227

228
### File Validation
229

230
Configure MIME type validation, file type restrictions, and custom validators.
231

232
```python { .api }
233
# MIME Type Validation
234
FILER_MIME_TYPE_WHITELIST = None
235
# list or None: Allowed MIME types (None = allow all)
236
# Example: ['image/jpeg', 'image/png', 'application/pdf']
237

238
# File Validators
239
FILE_VALIDATORS = [
240
    'filer.validation.validate_upload',
241
]
242
# list: List of file validation functions
243

244
# Image MIME Types
245
IMAGE_MIME_TYPES = [
246
    'image/jpeg',
247
    'image/jpg', 
248
    'image/png',
249
    'image/gif',
250
    'image/bmp',
251
    'image/tiff',
252
    'image/webp',
253
    'image/svg+xml',
254
]
255
# list: Recognized image MIME types
256

257
# Validation Functions
258
def validate_upload(file_obj):
259
    """
260
    Custom file validation function.
261
    
262
    Args:
263
        file_obj: File object to validate
264
        
265
    Raises:
266
        ValidationError: If file is invalid
267
    """
268

269
# SVG Validation (security)
270
FILER_VALIDATE_SVG = True
271
# bool: Enable SVG security validation (default: True)
272
```
273

274
### Admin Interface Customization
275

276
Customize the Django admin interface appearance and behavior.
277

278
```python { .api }
279
# Icon Library
280
ICON_CSS_LIB = (
281
    'filer/css/admin_filer.css',
282
)
283
# tuple: CSS files for admin icons
284

285
# Admin Templates
286
FILER_ADMIN_TEMPLATES = {
287
    'file_picker': 'admin/filer/widgets/admin_file.html',
288
    'folder_picker': 'admin/filer/widgets/admin_folder.html',
289
}
290
# dict: Custom admin widget templates
291

292
# JavaScript and CSS
293
FILER_STATIC_MEDIA_PREFIX = '/static/filer/'
294
# str: Prefix for filer static media URLs
295
```
296

297
### Integration Settings
298

299
Settings for integrating with other Django packages and systems.
300

301
```python { .api }
302
# Django CMS Integration
303
INSTALLED_APPS = [
304
    # ...
305
    'filer',
306
    'easy_thumbnails',
307
    'filer.contrib.django_cms',  # Optional CMS integration
308
]
309

310
# Easy Thumbnails Configuration
311
THUMBNAIL_ALIASES = {
312
    '': {
313
        'admin_clipboard_icon': {'size': (32, 32), 'crop': True},
314
        'admin_directory_listing_icon': {'size': (48, 48), 'crop': True},
315
        'admin_tiny_icon': {'size': (16, 16), 'crop': True},
316
    },
317
}
318

319
# Thumbnail Processors
320
THUMBNAIL_PROCESSORS = [
321
    'easy_thumbnails.processors.colorspace',
322
    'easy_thumbnails.processors.autocrop',
323
    'filer.thumbnail_processors.scale_and_crop_with_subject_location',
324
    'easy_thumbnails.processors.filters',
325
]
326
# list: Thumbnail processing pipeline
327

328
# ClamAV Antivirus Integration (optional)
329
FILER_CLAMAV_ENABLED = False
330
# bool: Enable ClamAV virus scanning (requires filer.contrib.clamav)
331

332
FILER_CLAMAV_SOCKET_PATH = '/var/run/clamav/clamd.ctl'
333
# str: Path to ClamAV socket
334
```
335

336
## Usage Examples
337

338
### Basic Configuration
339

340
```python
341
# settings.py
342
import os
343

344
# Basic filer setup
345
INSTALLED_APPS = [
346
    'django.contrib.admin',
347
    'django.contrib.auth',
348
    'django.contrib.contenttypes', 
349
    'django.contrib.sessions',
350
    'django.contrib.messages',
351
    'django.contrib.staticfiles',
352
    
353
    # Required for filer
354
    'filer',
355
    'easy_thumbnails',
356
]
357

358
# Media files configuration
359
MEDIA_URL = '/media/'
360
MEDIA_ROOT = os.path.join(BASE_DIR, 'media')
361

362
# Enable permissions
363
FILER_ENABLE_PERMISSIONS = True
364

365
# Default to public files
366
FILER_IS_PUBLIC_DEFAULT = True
367

368
# Upload limits
369
FILER_UPLOADER_MAX_FILE_SIZE = 50 * 1024 * 1024  # 50MB
370
```
371

372
### Production Storage Configuration
373

374
```python
375
# settings.py for production
376
import os
377

378
# Separate public and private media
379
FILER_STORAGES = {
380
    'public': {
381
        'main': {
382
            'ENGINE': 'django.core.files.storage.FileSystemStorage',
383
            'OPTIONS': {
384
                'location': os.path.join(BASE_DIR, 'media', 'filer_public'),
385
                'base_url': '/media/filer_public/',
386
            },
387
        },
388
        'thumbnails': {
389
            'ENGINE': 'django.core.files.storage.FileSystemStorage',
390
            'OPTIONS': {
391
                'location': os.path.join(BASE_DIR, 'media', 'filer_public_thumbnails'),
392
                'base_url': '/media/filer_public_thumbnails/',
393
            }, 
394
        },
395
    },
396
    'private': {
397
        'main': {
398
            'ENGINE': 'django.core.files.storage.FileSystemStorage',
399
            'OPTIONS': {
400
                'location': os.path.join(BASE_DIR, 'protected'),
401
                'base_url': '/protected/filer_private/',
402
            },
403
        },
404
        'thumbnails': {
405
            'ENGINE': 'django.core.files.storage.FileSystemStorage',
406
            'OPTIONS': {
407
                'location': os.path.join(BASE_DIR, 'protected', 'thumbnails'),
408
                'base_url': '/protected/filer_private_thumbnails/',
409
            },
410
        },
411
    },
412
}
413

414
# Use nginx for serving private files
415
FILER_SERVERS = {
416
    'private': {
417
        'main': {
418
            'ENGINE': 'filer.server.backends.nginx.NginxXAccelRedirectServer',
419
            'OPTIONS': {
420
                'location': '/protected/',
421
                'nginx_location': '/internal-protected/',
422
            },
423
        },
424
        'thumbnails': {
425
            'ENGINE': 'filer.server.backends.nginx.NginxXAccelRedirectServer', 
426
            'OPTIONS': {
427
                'location': '/protected/thumbnails/',
428
                'nginx_location': '/internal-protected/thumbnails/',
429
            },
430
        },
431
    },
432
}
433
```
434

435
### Custom Image Model Configuration
436

437
```python
438
# models.py
439
from filer.models.abstract import BaseImage
440

441
class CustomImage(BaseImage):
442
    credit = models.CharField(max_length=255, blank=True)
443
    keywords = models.TextField(blank=True)
444
    
445
    class Meta:
446
        app_label = 'myapp'
447

448
# settings.py  
449
FILER_IMAGE_MODEL = 'myapp.CustomImage'
450

451
# Update file models list
452
FILER_FILE_MODELS = (
453
    'filer.models.File',
454
    'myapp.models.CustomImage',  # Use custom image model
455
)
456
```
457

458
### Validation Configuration
459

460
```python
461
# settings.py
462
from filer.validation import validate_upload
463

464
# Custom file validation
465
def custom_validate_upload(file_obj):
466
    from django.core.exceptions import ValidationError
467
    
468
    # Size validation
469
    if file_obj.size > 100 * 1024 * 1024:  # 100MB
470
        raise ValidationError('File too large')
471
    
472
    # Name validation  
473
    if 'virus' in file_obj.name.lower():
474
        raise ValidationError('Suspicious filename')
475

476
# File validation pipeline
477
FILE_VALIDATORS = [
478
    validate_upload,
479
    'myapp.validators.custom_validate_upload',
480
]
481

482
# MIME type restrictions
483
FILER_MIME_TYPE_WHITELIST = [
484
    'image/jpeg',
485
    'image/png', 
486
    'image/gif',
487
    'application/pdf',
488
    'text/plain',
489
]
490

491
# Enable SVG validation for security
492
FILER_VALIDATE_SVG = True
493
```
494

495
### Development vs Production Settings
496

497
```python
498
# settings/base.py
499
FILER_ENABLE_PERMISSIONS = True
500
FILER_IS_PUBLIC_DEFAULT = True
501

502
# settings/development.py
503
from .base import *
504

505
FILER_DEBUG = True
506
FILER_ENABLE_LOGGING = True
507

508
# Simple file storage for development
509
MEDIA_ROOT = os.path.join(BASE_DIR, 'media')
510
MEDIA_URL = '/media/'
511

512
# settings/production.py
513
from .base import *
514

515
FILER_DEBUG = False
516
FILER_ENABLE_LOGGING = True
517

518
# Production storage with separate public/private
519
FILER_STORAGES = {
520
    # ... production storage config
521
}
522

523
# Security settings
524
FILER_UPLOADER_MAX_FILE_SIZE = 10 * 1024 * 1024  # 10MB
525
FILER_MIME_TYPE_WHITELIST = [
526
    'image/jpeg', 'image/png', 'application/pdf'
527
]
528
```