{"id":49532491,"url":"https://github.com/shihebamrii/local-file-server","last_synced_at":"2026-05-02T08:34:16.372Z","repository":{"id":323921966,"uuid":"1095222935","full_name":"shihebamrii/local-file-server","owner":"shihebamrii","description":"Lightweight Flask app for browsing Windows PC files over LAN. Download, upload to safe folder, auto-generated password, session login. Ideal for trusted home networks","archived":false,"fork":false,"pushed_at":"2025-11-12T20:22:20.000Z","size":9,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2025-11-12T22:04:28.468Z","etag":null,"topics":["file-server","file-sharing-home-network","flask","flask-application","lan","local-network","python","waitress","web-file-manager","windows"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/shihebamrii.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-11-12T18:57:08.000Z","updated_at":"2025-11-12T20:29:09.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/shihebamrii/local-file-server","commit_stats":null,"previous_names":["shihebamrii/local-file-server"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/shihebamrii/local-file-server","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shihebamrii%2Flocal-file-server","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shihebamrii%2Flocal-file-server/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shihebamrii%2Flocal-file-server/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shihebamrii%2Flocal-file-server/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/shihebamrii","download_url":"https://codeload.github.com/shihebamrii/local-file-server/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shihebamrii%2Flocal-file-server/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32528303,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-02T01:12:54.858Z","status":"online","status_checked_at":"2026-05-02T02:00:05.923Z","response_time":132,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["file-server","file-sharing-home-network","flask","flask-application","lan","local-network","python","waitress","web-file-manager","windows"],"created_at":"2026-05-02T08:34:15.624Z","updated_at":"2026-05-02T08:34:16.358Z","avatar_url":"https://github.com/shihebamrii.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\n# Local Network File Server\n\n**Full PC Browser Access with Auto-Generated Password and Secure Uploads**\n\nThis lightweight Python Flask app transforms your Windows PC into a local file server, allowing seamless browsing and file management over your LAN from any browser. Perfect for quick file sharing within trusted networks!\n\n## Key Features\n- **Full Filesystem Browsing**: Explore your PC's directories starting from a configurable `ROOT_DIR` (defaults to `C:\\`).\n- **Easy Downloads**: Click to download files from any browsable folder.\n- **Safe Uploads**: Files are saved to a dedicated `uploads/` folder to bypass Windows permission issues.\n- **Auto-Generated Password**: A new random admin password is created on every startup, stored in `.env`, and printed to the console for easy access.\n- **Simple Login Protection**: A lightweight login screen secures access over the LAN.\n\n⚠️ **Security Reminder**: This app is designed for **trusted local networks only**. Do **not** expose it to the public internet without additional security measures like hardened authentication, TLS, a reverse proxy, or VPN.\n\n## Project Structure\n```\nlocal-network-file-server/\n├── app.py                # Main Flask app (auto password generation)\n├── run_waitress.py       # Optional: Run with Waitress for Windows\n├── requirements.txt\n├── .env.example\n├── .gitignore\n├── README.md             # (This file)\n├── templates/\n│   ├── index.html\n│   └── login.html\n├── static/\n│   └── style.css\n└── uploads/              # Created at runtime (writable upload target)\n```\n\n## Quick Summary: What the App Does\n1. **Startup Password Generation**: On launch, `app.py` creates a secure random password, saves it as `ADMIN_PASSWORD=\u003cpassword\u003e` in `.env` (appends if the file exists), and prints it to the console.\n2. **Browsable UI**: Serves an interactive interface to list directories and files under `ROOT_DIR` (default: `C:\\`).\n3. **File Downloads**: Simply click a file to download it; navigate directories via URL paths.\n4. **Secure Uploads**: Browser uploads are redirected to `ROOT_DIR/uploads/\u003ccurrent_path\u003e` to avoid permission errors in protected folders.\n5. **Session-Based Login**: Protects the UI with a password check against the generated value.\n\n## Requirements\n- **Operating System**: Windows (tested on Windows 10/11).\n- **Python**: 3.8+ (3.11+ recommended).\n- **Git**: Optional, for cloning the repo.\n\n### Python Packages (from `requirements.txt`)\n```\nFlask\u003e=2.2\nwaitress\u003e=2.1\npython-dotenv\u003e=1.0\n```\n\n## Installation \u0026 Setup (Windows)\nOpen PowerShell and follow these steps:\n\n```powershell\n# Clone or copy the repo, then:\ncd C:\\path\\to\\local-file-server\npython -m venv venv\n# If PowerShell blocks scripts for venv activation, enable temporarily:\nSet-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope Process -Force\n# Activate venv (PowerShell):\n.\\venv\\Scripts\\Activate.ps1\n# Install dependencies\npip install -r requirements.txt\n```\n\n## .env File\n- Copy `.env.example` to `.env` to override defaults. The app will append `ADMIN_PASSWORD` on every start if needed.\n\nContents of `.env.example`:\n```\n# Copy to .env and edit values if you want to override defaults\nFLASK_SECRET=changeme-please\nPORT=8000\nMAX_CONTENT_LENGTH=209715200\nROOT_DIR=C:\\\\\n```\n\n**Note**: The app uses `ROOT_DIR` from the environment if set; otherwise, it defaults to `C:\\`.\n\n## How the Auto-Password Works\n- On every startup, a 12-character random password (letters, digits, punctuation) is generated and assigned to `ADMIN_PASSWORD`.\n- If `.env` exists, it appends `ADMIN_PASSWORD=\u003cnew-password\u003e` to ensure the latest is saved.\n- The password is printed to the console, e.g.:\n  ```\n  New admin password generated: s%3R!aB7... (example)\n  ```\n- Use this to log in at `http://\u003cyour-pc-ip\u003e:\u003cport\u003e`.\n\n## Running the App\n### Dev Server (Quick Test – Not for Production)\n```powershell\npython app.py\n# Or explicitly (optional):\n$env:FLASK_APP = \"app.py\"\nflask run --host=0.0.0.0 --port=8000\n```\n\n### Recommended: Waitress for Multi-Client LAN Usage\n```powershell\npython run_waitress.py\n```\n\nWaitress provides a more robust server for Windows compared to Flask's built-in dev server.\n\n## Windows Firewall Configuration\nIf devices on the LAN can't connect, allow the port through Firewall (run PowerShell as Administrator):\n\n```powershell\nNew-NetFirewallRule -DisplayName \"Allow Flask 8000\" -Direction Inbound -Action Allow -Protocol TCP -LocalPort 8000 -Profile Private,Domain\n```\n\n## Accessing from Another Device on the LAN\n1. Find your PC's IP:\n   ```powershell\n   ipconfig\n   # Look for IPv4 Address under your active adapter\n   ```\n\n2. On another device (phone/laptop), open a browser and visit:\n   ```\n   http://\u003cyour-pc-ip\u003e:8000\n   ```\n   You'll be prompted for the password from the console.\n\n## Upload Behavior \u0026 Permissions\n- To prevent `PermissionError` in protected folders (e.g., root `C:\\`), uploads are saved to a dedicated `uploads/` folder within `ROOT_DIR`.\n- **Example**: Uploading while browsing `C:\\Users\\You\\Documents` saves to `C:\\uploads\\C\\Users\\You\\Documents\\` (created automatically). This keeps things organized and error-free.\n\n## Security Notes (Read Carefully)\n- This app is **not** designed for public exposure. For remote access, use a VPN (e.g., Tailscale, WireGuard), secure reverse proxy with TLS, and strong authentication.\n- The `.env` file contains secrets – it's already in `.gitignore` by default.\n- **Enhancements to Consider**: Hashed passwords, single-use tokens, IP allowlists, rate-limiting, and disabling listings for sensitive folders.\n\n## Customization\n- Change `ROOT_DIR` via `.env` or environment variable:\n  ```powershell\n  setx ROOT_DIR \"D:\\\\some\\folder\"\n  # Reopen terminal, then run python app.py\n  ```\n- Adjust `PORT`, `MAX_CONTENT_LENGTH`, or `FLASK_SECRET` in `.env`.\n\n## Troubleshooting\n- **No Output on Startup**: Ensure the correct file is run and venv is activated. Add a `print(\"Starting\")` line for debugging.\n- **PermissionError on Upload**: Handled by saving to `uploads/`; confirm the folder is writable.\n- **Can't Access from Phone**: Verify same Wi-Fi network, check Firewall, and test with `Test-NetConnection -ComputerName \u003cip\u003e -Port 8000`.\n\n## Pushing to GitHub\n`.env` is ignored by default. Before pushing:\n```powershell\ngit init\ngit add .\ngit commit -m \"Initial commit\"\ngit branch -M main\ngit remote add origin https://github.com/yourusername/local-file-server.git\ngit push -u origin main\n```\n\n## Next Steps / TODO\n- Add hashed password storage instead of plain-text in `.env`.\n- Optional: Implement HTTP Basic Auth and rate-limiting.\n- Optional: Dockerfile for easier deployment.\n- Optional: Add UI controls (rename, delete, create folder).\n\n## License\nThis project is released under the MIT License. Add a `LICENSE` file if publishing.\n```","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fshihebamrii%2Flocal-file-server","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fshihebamrii%2Flocal-file-server","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fshihebamrii%2Flocal-file-server/lists"}