--- title: "Local File Storage - DreamFactory Documentation" source: "http://wiki.dreamfactory.com/Local_File_Storage" canonical_url: "http://wiki.dreamfactory.com/Local_File_Storage" converted_at: "2026-10-22T18:50:38.260Z" format: "markdown" converted_by: "html-to-md-ai" --- []() # Local File Storage From DreamFactory Wiki [Jump to navigation](#mw-head) [Jump to search](#searchInput) **Create a REST API for local file storage on the DreamFactory server with full CRUD operations** ## Contents - [1 Local File Storage](#Local_File_Storage) - [1.1 Use Cases](#Use_Cases) - [1.2 Creating a Local File Storage Service](#Creating_a_Local_File_Storage_Service) - [1.2.1 Step 1: Navigate to API Generation](#Step_1:_Navigate_to_API_Generation) - [1.2.2 Step 2: Create New Service](#Step_2:_Create_New_Service) - [1.2.3 Step 3: Configure Service Details](#Step_3:_Configure_Service_Details) - [1.2.4 Step 4: Configure Storage Path](#Step_4:_Configure_Storage_Path) - [1.2.5 Step 5: Save and Test](#Step_5:_Save_and_Test) - [1.3 Configuration Options](#Configuration_Options) - [1.3.1 Advanced Options](#Advanced_Options) - [1.4 API Endpoints](#API_Endpoints) - [1.5 API Examples](#API_Examples) - [1.5.1 List Directory Contents](#List_Directory_Contents) - [1.5.2 Create a Folder](#Create_a_Folder) - [1.5.3 Upload a File](#Upload_a_File) - [1.5.4 Download a File](#Download_a_File) - [1.5.5 Get File Properties](#Get_File_Properties) - [1.5.6 Delete a File](#Delete_a_File) - [1.5.7 Delete a Folder](#Delete_a_Folder) - [1.6 File Upload Limits](#File_Upload_Limits) - [1.6.1 Nginx Configuration](#Nginx_Configuration) - [1.6.2 PHP Configuration](#PHP_Configuration) - [1.7 Common Errors](#Common_Errors) - [1.7.1 Troubleshooting Permissions](#Troubleshooting_Permissions) - [1.8 Security Considerations](#Security_Considerations) - [1.8.1 Path Traversal Protection](#Path_Traversal_Protection) - [1.8.2 Role-Based Access Control](#Role-Based_Access_Control) - [1.9 Next Steps](#Next_Steps) # Local File Storage DreamFactory's Local File Storage connector provides REST API access to files stored directly on the DreamFactory server's filesystem. This is ideal for development, testing, and scenarios where cloud storage is not required. --- ## Use Cases - **Development and testing**: Quick setup without external dependencies - **Application assets**: Store images, documents, and static files - **Temporary file processing**: Upload files for server-side processing - **Small-scale deployments**: When cloud storage is unnecessary overhead - **Air-gapped environments**: No internet connectivity required **⚠️ Warning: Production Considerations** For production deployments, consider cloud storage (S3, Azure Blob) for: - Horizontal scaling (multiple DreamFactory instances) - Backup and disaster recovery - CDN integration - Larger storage capacity --- ## Creating a Local File Storage Service ### Step 1: Navigate to API Generation Log in to your DreamFactory instance using an administrator account and select the **API Generation & Connections** tab. Set your API Type to **File**. ### Step 2: Create New Service Click the purple plus button to create a new file service, then search for and select **Local File Storage**. ### Step 3: Configure Service Details Field Description Example Name Service name (lowercase, alphanumeric, used in API URL) `files` Label Display name in admin console `Local Files` Description Service description `Local file storage for application assets` ### Step 4: Configure Storage Path In the **Config** section, specify the root folder path: Field Description Example Root Folder Absolute path on the server `/var/www/storage/files` **⚠️ Warning: Permissions** Ensure the web server user (e.g., `www-data`, `nginx`) has read/write permissions on the specified root folder: ``` sudo mkdir -p /var/www/storage/files sudo chown -R www-data:www-data /var/www/storage/files sudo chmod -R 755 /var/www/storage/files ``` ### Step 5: Save and Test Click **Save** to create the service. Navigate to **API Docs** to view the generated endpoints and test operations. --- ## Configuration Options Field Type Required Default Description `root_folder` string Yes - Absolute path to the storage directory `public_path` string No - Public URL path if files are web-accessible `is_public` boolean No false Allow unauthenticated file downloads ### Advanced Options Field Type Default Description `cache_enabled` boolean false Enable response caching `cache_ttl` integer 0 Cache time-to-live in seconds `allow_upsert` boolean true Allow PUT to create new files --- ## API Endpoints Once configured, DreamFactory generates these endpoints: Method Endpoint Description `GET` `/api/v2/{service_name}/` List root directory `GET` `/api/v2/{service_name}/{path}/` List folder contents `GET` `/api/v2/{service_name}/{path}` Download file `POST` `/api/v2/{service_name}/` Create folder or upload file `POST` `/api/v2/{service_name}/{path}/` Create subfolder or upload file `PUT` `/api/v2/{service_name}/{path}` Replace file contents `PATCH` `/api/v2/{service_name}/{path}` Update file properties `DELETE` `/api/v2/{service_name}/{path}` Delete file or folder --- ## API Examples ### List Directory Contents ``` curl -X GET "https://example.com/api/v2/files/" \ -H "X-DreamFactory-API-Key: YOUR_API_KEY" ``` **Response:** ``` { "resource": [ { "path": "images/", "type": "folder", "name": "images", "last_modified": "2026-02-10T14:30:00Z" }, { "path": "config.json", "type": "file", "name": "config.json", "content_type": "application/json", "content_length": 2048, "last_modified": "2026-02-09T10:15:00Z" } ] } ``` ### Create a Folder ``` curl -X POST "https://example.com/api/v2/files/" \ -H "X-DreamFactory-API-Key: YOUR_API_KEY" \ -H "X-Folder-Name: documents" ``` **Response:** ``` { "name": "documents", "path": "documents/" } ``` ### Upload a File Using the file path in the URL: ``` curl -X POST "https://example.com/api/v2/files/documents/report.pdf" \ -H "X-DreamFactory-API-Key: YOUR_API_KEY" \ -H "Content-Type: application/pdf" \ --data-binary @report.pdf ``` Using the `X-File-Name` header: ``` curl -X POST "https://example.com/api/v2/files/documents/" \ -H "X-DreamFactory-API-Key: YOUR_API_KEY" \ -H "X-File-Name: report.pdf" \ -H "Content-Type: application/pdf" \ --data-binary @report.pdf ``` **Response:** ``` { "name": "report.pdf", "path": "documents/report.pdf", "content_type": "application/pdf", "content_length": 102400 } ``` ### Download a File ``` curl -X GET "https://example.com/api/v2/files/documents/report.pdf" \ -H "X-DreamFactory-API-Key: YOUR_API_KEY" \ -o report.pdf ``` ### Get File Properties Add `?include_properties=true` to get metadata without downloading: ``` curl -X GET "https://example.com/api/v2/files/documents/report.pdf?include_properties=true" \ -H "X-DreamFactory-API-Key: YOUR_API_KEY" ``` **Response:** ``` { "path": "documents/report.pdf", "name": "report.pdf", "type": "file", "content_type": "application/pdf", "content_length": 102400, "last_modified": "2026-02-10T15:45:00Z" } ``` ### Delete a File ``` curl -X DELETE "https://example.com/api/v2/files/documents/old-report.pdf" \ -H "X-DreamFactory-API-Key: YOUR_API_KEY" ``` ### Delete a Folder Add `?force=true` to delete non-empty folders: ``` curl -X DELETE "https://example.com/api/v2/files/old-documents/?force=true" \ -H "X-DreamFactory-API-Key: YOUR_API_KEY" ``` --- ## File Upload Limits Upload size limits are controlled by your web server and PHP configuration, not DreamFactory. ### Nginx Configuration Add to your `nginx.conf` or site configuration: ``` client_max_body_size 100M; ``` ### PHP Configuration Modify `php.ini`: ``` upload_max_filesize = 100M post_max_size = 105M ``` Restart your web server and PHP-FPM after making changes. --- ## Common Errors Error Code Message Cause Solution 400 Invalid path Path contains invalid characters Use alphanumeric characters, dashes, underscores 403 Forbidden Permission denied on filesystem Check folder permissions for web server user 404 Not Found File or folder does not exist Verify the path exists on the server 409 Conflict File already exists Use PUT to overwrite or delete first 413 Payload Too Large File exceeds upload limit Increase server upload limits 500 Internal Server Error Server-side error Check DreamFactory logs for details ### Troubleshooting Permissions If you receive 403 errors, verify filesystem permissions: ``` # Check current permissions ls -la /var/www/storage/files # Fix ownership sudo chown -R www-data:www-data /var/www/storage/files # Fix permissions (directories need execute bit) sudo find /var/www/storage/files -type d -exec chmod 755 {} \; sudo find /var/www/storage/files -type f -exec chmod 644 {} \; ``` --- ## Security Considerations ### Path Traversal Protection DreamFactory sanitizes paths to prevent directory traversal attacks. Requests containing `../` or absolute paths outside the root folder are rejected. ### Role-Based Access Control Configure RBAC to restrict file operations: 1. Navigate to **Roles** in the admin console 2. Select or create a role 3. Under **Access**, add the file service 4. Configure allowed paths and operations: - **GET** for read-only access - **POST** for upload-only - **DELETE** to allow deletions Example: Allow uploads to `/uploads/` but not access to `/config/`: Path Methods `uploads/*` GET, POST `public/*` GET --- ## Next Steps - **[AWS S3](/Aws_S3)**: Migrate to cloud storage for production - **[File Services Overview](/File_Services_Overview)**: Compare all file storage options - **[Role-Based Access Control](/Security/Role_Based_Access)**: Configure fine-grained permissions Retrieved from "[https://wiki.dreamfactory.com/index.php?title=Local_File_Storage&oldid=975](https://wiki.dreamfactory.com/index.php?title=Local_File_Storage&oldid=975)" [Categories](/Special:Categories): - [Local Storage](/index.php?title=Category:Local_Storage&action=edit&redlink=1) - [File Storage](/Category:File_Storage) - [Rest Api](/Category:Rest_Api) - [API](/Category:API) - [Difficulty Beginner](/Category:Difficulty_Beginner)