{"id":44416510,"url":"https://github.com/adhupraba/fshare","last_synced_at":"2026-02-12T08:34:39.227Z","repository":{"id":268021527,"uuid":"902954422","full_name":"adhupraba/fshare","owner":"adhupraba","description":"FShare is a secure and robust file-sharing application that enables users to upload, share, and manage encrypted files.","archived":false,"fork":false,"pushed_at":"2025-01-21T18:34:52.000Z","size":1820,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-01-21T19:36:33.628Z","etag":null,"topics":["cryptography","django","django-rest-framework","encryption-decryption","file-sharing","reactjs","security"],"latest_commit_sha":null,"homepage":"https://fshare.adhupraba.com","language":"TypeScript","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/adhupraba.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}},"created_at":"2024-12-13T16:03:31.000Z","updated_at":"2025-01-21T18:34:56.000Z","dependencies_parsed_at":"2025-01-10T13:19:38.645Z","dependency_job_id":"8b9c1cda-9235-460c-994e-7d0623161897","html_url":"https://github.com/adhupraba/fshare","commit_stats":null,"previous_names":["adhupraba/fshare"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/adhupraba/fshare","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adhupraba%2Ffshare","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adhupraba%2Ffshare/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adhupraba%2Ffshare/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adhupraba%2Ffshare/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/adhupraba","download_url":"https://codeload.github.com/adhupraba/fshare/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adhupraba%2Ffshare/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29361819,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-12T01:03:07.613Z","status":"online","status_checked_at":"2026-02-12T02:00:06.911Z","response_time":55,"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":["cryptography","django","django-rest-framework","encryption-decryption","file-sharing","reactjs","security"],"created_at":"2026-02-12T08:34:38.699Z","updated_at":"2026-02-12T08:34:39.222Z","avatar_url":"https://github.com/adhupraba.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# **FShare - File Sharing Application**\n\nFShare is a secure and robust file-sharing application that enables users to upload, share, and manage encrypted files. It includes a **Django backend** (server) for handling API requests and business logic, and a **React/Vite frontend** (client) for the user interface.\n\nThe live project is hosted at https://fshare.adhupraba.com/\n\nTo know how the application works, please see the [Application Workflow](#application-workflow) section.\n\n---\n\n## **Table of Contents**\n\n- [Setup Instructions](#setup-instructions)\n  - [Running with Docker](#running-with-docker)\n  - [Running Locally](#running-locally)\n    - [Backend Setup](#backend-setup-django-server)\n    - [Frontend Setup](#frontend-setup-react-client)\n- [Generating Unique Secret Keys](#secret-keys)\n- [Application Workflow](#application-workflow)\n- [API Access](#api-access)\n- [Troubleshooting](#troubleshooting)\n\n---\n\n## **Setup Instructions**\n\n### **Running with Docker**\n\nThe project includes a Docker setup for running both the client and server simultaneously.\n\n1. **Setup Environment Variables**:\n\n- In the project root, copy `.env.example` to `.env`:\n\n  ```bash\n  cp .env.client.example .env.client\n  cp .env.server.example .env.server\n  ```\n\n- Update the `.env.client` and `.env.server` files with appropriate values.\n\n  - Sample .env.client:\n\n    ```bash\n    VITE_API_URL=\"https://localhost\"\n    ```\n\n  - Sample .env.server:\n\n    ```bash\n    SECRET_KEY=\"EB585CAE79C5716B446A8506D6E81313\" # 32 bytes key used to encrypt mfa secret\n    SERVER_FILE_ENCRYPTION_KEY=\"A17FB154FC9BD982C137515C9DC36216\" # 32 bytes for AES-256. used for encrypting files\n    MFA_JWT_SECRET_KEY=\"369FD1B0BFC1C6070DAF41FD490BE641963B17E5A93108070F7AD04BAC4504D9\" # secret key used to generate temporary jwt tokens for mfa registration\n    AUTH_JWT_SECRET_KEY=\"1B7FD022D3499C0BCBE8D9CB1EE0C97594B2491BEB86C28380731C46D294EF28\" # secret key used to generate login auth tokens\n    DEBUG_MODE=\"False\" # True or False\n    ALLOWED_HOSTS=\"localhost,127.0.0.1\" # allowed hosts used in settings.py\n    CORS_ALLOWED_ORIGINS=\"http://127.0.0.1,https://127.0.0.1,http://localhost,https://localhost\" # allowed hosts used in settings.py\n    ```\n\n- Please generate unique keys for secret env variables at the time of running the application for better security. See [Generating Unique Secret Keys](#secret-keys) section.\n\n2. **Custom certificates for SSL/TLS**\n\n- The client docker image by default creates a self signed SSL certificate with a validity of 1 year\n\n- To overwrite the certificate that comes with the docker image:\n\n  - Create a `certs` folder in the root of the project\n\n    ```bash\n    mkdir certs\n    ```\n\n  - Generate self signed SSL certificates\n\n    ```bash\n    openssl req -x509 -nodes -days 365 -newkey rsa:2048 \\\n      -keyout certs/server.key -out certs/server.crt \\\n      -subj \"/CN=localhost\"\n    ```\n\n  - Add `volumes` to `client` service pointing to the `certs` folder:\n\n    ```bash\n    volumes:\n        - ./certs/server.crt:/etc/nginx/certs/server.crt\n        - ./certs/server.key:/etc/nginx/certs/server.key\n    ```\n\n3. **Adding new environment variables (Important)**:\n\nWhenever a new `VITE_` env needs to be added to the client, make sure to update the `dockerfile.dev.client` and `dockerfile.prod.client` with a placeholder value and add that env entry into `entrypoint.sh` so at runtime the placeholder is replaced with appropriate value taken from the supplied `.env.client` file to the docker compose file.\n\n4. **Build and Run the Docker Containers**:\n\n- From the project root directory, run:\n\n  ```bash\n  docker compose -f docker-compose.dev.yaml up --build\n  ```\n\n5. **Access the application**:\n\n- Frontend: `https://localhost/`\n\n- Backend: `https://localhost/api/`\n\n6. **Create super user for Django admin**:\n\n- To create a super user for accessing the admin portal:\n\n  ```bash\n  docker exec -it \u003cbackend_container_id\u003e sh\n  ```\n\n  ```bash\n  python manage.py createsuperuser\n  ```\n\n- Don't use this admin user as a normal application user as the RSA keys and master password will not be generated.\n\n7. **Promoting Regular User to Admin Role**\n\n- When a regular user signs up using the application's registration flow, the user can be converted to an `Admin` through the admin panel (`https://localhost/admin/`) using the previously created admin user's credentials.\n\n- Note: The admin panel workaround is required only for the first `Regular User` to be converted to `Admin` role.\n\n- Now the newly converted `Admin` role user can change the roles of any other user who registers in the application.\n\n### **Running Locally**\n\n#### **Backend Setup (Django Server)**\n\n1. **Create a Virtual Environment**:\n\n```bash\npython -m venv .venv\nsource .venv/bin/activate  # On Windows use `.venv\\Scripts\\activate`\n```\n\n2. **Navigate to the Server Directory**:\n\n```bash\ncd server\n```\n\n3. **Install Dependencies**:\n\n```bash\npip install --upgrade pip\npip install -r requirements.txt\n```\n\n4. **Setup Environment Variables**:\n\n- Copy `.env.example` to `.env`:\n\n  ```bash\n  cp .env.example .env\n  ```\n\n- Update the `.env` file with appropriate values. Here are some sample values:\n\n  ```bash\n  SECRET_KEY=\"EB585CAE79C5716B446A8506D6E81313\" # 32 bytes key used to encrypt mfa secret\n  SERVER_FILE_ENCRYPTION_KEY=\"A17FB154FC9BD982C137515C9DC36216\" # 32 bytes for AES-256. used for encrypting files\n  MFA_JWT_SECRET_KEY=\"369FD1B0BFC1C6070DAF41FD490BE641963B17E5A93108070F7AD04BAC4504D9\" # secret key used to generate temporary jwt tokens for mfa registration\n  AUTH_JWT_SECRET_KEY=\"1B7FD022D3499C0BCBE8D9CB1EE0C97594B2491BEB86C28380731C46D294EF28\" # secret key used to generate login auth tokens\n  DEBUG_MODE=\"False\" # True or False\n  ALLOWED_HOSTS=\"localhost,127.0.0.1\" # allowed hosts used in settings.py\n  CORS_ALLOWED_ORIGINS=\"http://localhost:5173,http://127.0.0.1:5173,http://localhost,https://localhost\" # allowed hosts used in settings.py\n  ```\n\n- Please generate unique keys for secret env variables at the time of running the application for better security. See [Generating Unique Secret Keys](#secret-keys) section.\n\n5. **Apply Migrations**:\n\n```bash\npython manage.py migrate\n```\n\n6. **Create a super user to access the Django admin portal**:\n\n```bash\npython manage.py createsuperuser\n```\n\nDon't use this admin user as a normal application user as the RSA keys and master password will not be generated.\n\n7. **Promoting Regular User to Admin Role**\n\n- When a regular user signs up using the application's registration flow, the user can be converted to an `Admin` through the admin panel (`http://localhost:8000/admin/`) using the previously created admin user's credentials.\n\n- Note: The admin panel workaround is required only for the first `Regular User` to be converted to `Admin` role.\n\n- Now the newly converted `Admin` role user can change the roles of any other user who registers in the application.\n\n8. **Start the Server**:\n\n```bash\npython manage.py runserver\n```\n\nThe backend APIs will be available at `http://localhost:8000/api/`.\n\n---\n\n#### **Frontend Setup (React/Vite Client)**\n\n1. **Navigate to the Client Directory**:\n\n```bash\ncd client\n```\n\n2. **Install Dependencies**:\n\n```bash\nnpm install\n```\n\n3. **Setup Environment Variables**:\n\n- Copy `.env.example` to `.env`:\n\n  ```bash\n  cp .env.example .env\n  ```\n\n- Update the `.env` file with appropriate values. Here are some sample values:\n\n  ```bash\n  VITE_API_URL=\"http://localhost:8000\"\n  ```\n\n- Please generate unique keys at the time of running the application for better security\n\n4. **Start the Frontend Development Server**:\n\n```bash\nnpm run dev\n```\n\nThe frontend will be available at `http://localhost:5173/`.\n\n---\n\n## **Generating Unique Secret Keys**\n\n```bash\n  # generates 32 bytes key (use this for generating secret and file encryption key)\n  openssl enc -aes-128-cbc -k secret -P -md sha1\n\n  # generates 64 bytes key (use this for generating jwt secrets)\n  openssl enc -aes-256-cbc -k secret -P -md sha1\n```\n\n---\n\n## **Application Workflow**\n\nThe following sequence diagram ilustrates the flow of the application:\n\n![FShare Sequence Diagram](sequence-diagram.png)\n\nIt shows how the client and server interact during user registration, user login, file upload and file sharing workflows.\n\n---\n\n## **API Access**\n\nTo test backend endpoints, use tools like Postman or curl.\nExample endpoint for login:\n\n```bash\n# Docker setup\nPOST http://localhost/api/auth/login/\n\n# Local setup\nPOST http://localhost:8000/api/auth/login/\n```\n\nFor full API documentation, refer to the backend `urls.py`.\n\n---\n\n## **Troubleshooting**\n\n### **Backend Issues**:\n\n- Verify that the `.env` file exists and contains correct values.\n\n- Check database migrations:\n\n  ```bash\n  python manage.py showmigrations\n  python manage.py migrate\n  ```\n\n### **Frontend Issues**:\n\n- Ensure the `VITE_API_URL` matches your backend server URL.\n\n- Restart the frontend development server:\n\n  ```bash\n  npm run dev\n  ```\n\n### **Docker Issues**:\n\n- If volumes are not persisting, ensure permissions are correct for `server/data` and `server/media`.\n\n- Rebuild containers to apply changes:\n\n  ```bash\n  docker-compose -f docker-compose.dev.yaml down --volumes\n  docker-compose -f docker-compose.dev.yaml up --build\n  ```\n\n---\n\nYou’re now ready to run and develop FShare locally or using Docker! 🚀\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fadhupraba%2Ffshare","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fadhupraba%2Ffshare","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fadhupraba%2Ffshare/lists"}