{"id":42750755,"url":"https://github.com/kumarmuthu/custom-https-server","last_synced_at":"2026-01-29T19:33:27.398Z","repository":{"id":333264985,"uuid":"1127246905","full_name":"kumarmuthu/custom-https-server","owner":"kumarmuthu","description":"A lightweight, Python-based Custom HTTP/HTTPS Server designed to run as a Linux systemd service or a macOS launchd agent. It is ideal for securely serving static files, logs, test results, build artifacts, or internal documentation.","archived":false,"fork":false,"pushed_at":"2026-01-18T08:50:41.000Z","size":401,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-01-18T17:23:45.425Z","etag":null,"topics":["automation","cicd","devops","https","https-server","launchd","linux","macos","open-source","python3","secure-server","static-server","systemd","systemd-service","web-server"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/kumarmuthu.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","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":"2026-01-03T13:46:34.000Z","updated_at":"2026-01-18T08:50:45.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/kumarmuthu/custom-https-server","commit_stats":null,"previous_names":["kumarmuthu/custom-https-server"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/kumarmuthu/custom-https-server","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kumarmuthu%2Fcustom-https-server","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kumarmuthu%2Fcustom-https-server/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kumarmuthu%2Fcustom-https-server/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kumarmuthu%2Fcustom-https-server/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kumarmuthu","download_url":"https://codeload.github.com/kumarmuthu/custom-https-server/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kumarmuthu%2Fcustom-https-server/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28883091,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-29T19:23:39.025Z","status":"ssl_error","status_checked_at":"2026-01-29T19:22:11.631Z","response_time":59,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":["automation","cicd","devops","https","https-server","launchd","linux","macos","open-source","python3","secure-server","static-server","systemd","systemd-service","web-server"],"created_at":"2026-01-29T19:33:26.759Z","updated_at":"2026-01-29T19:33:27.393Z","avatar_url":"https://github.com/kumarmuthu.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Custom HTTPS Server\n\n![Python](https://img.shields.io/badge/python-3.x-blue.svg)\n![License](https://img.shields.io/badge/license-MIT-green.svg)\n![Platform](https://img.shields.io/badge/platform-linux%20%7C%20macOS-lightgrey.svg)\n[![Build Status](https://github.com/kumarmuthu/custom-https-server/actions/workflows/python-app.yml/badge.svg)](https://github.com/kumarmuthu/custom-https-server/actions/workflows/python-app.yml)\n\n![GitHub Forks](https://img.shields.io/github/forks/kumarmuthu/custom-https-server?style=for-the-badge)\n![GitHub Stars](https://img.shields.io/github/stars/kumarmuthu/custom-https-server?style=for-the-badge)\n![GitHub Contributors](https://img.shields.io/github/contributors/kumarmuthu/custom-https-server?style=for-the-badge)\n\nA lightweight, Python-based **Custom HTTP/HTTPS Server** designed to run as a **Linux systemd service** or a **macOS `launchd` agent**. It is ideal for securely serving static files, logs, test results, build artifacts, or\ninternal documentation.\n\nThis version includes:\n\n* Native **HTTPS support** using a configurable SSL certificate and key\n* Optional **HTTP → HTTPS redirection**\n* Dynamic configuration loading from `/usr/local/etc/custom-https-server.conf` with local fallback\n* Automatic creation and management of log files in the user’s home directory\n* OS-specific defaults optimized for **Linux** and **macOS**\n* Threaded **HTTP and HTTPS** servers with optional authentication support\n* **Read and Write access modes** to control UI and file operations:\n\n    * **Read mode**\n\n        * No upload or delete buttons\n        * No file-selection checkboxes\n        * No JavaScript errors\n        * Breadcrumb navigation, search, and sorting fully functional\n\n    * **Write mode**\n\n        * Full interactive web UI enabled\n        * File upload, delete, progress indicator, and select-all supported\n        * Clean separation of HTML and JavaScript logic\n\n---\n\n## ✅ Features\n\n* **Pure Python 3** — no external dependencies\n* Serves any local directory\n* MIME-type aware (`.log`, `.tap`, `.xml`, `.html`, `.pdf`, `.md`, etc.)\n* Works as:\n\n    * **systemd service** on Linux\n    * **launchd agent** on macOS\n* Supports both **HTTP and HTTPS** simultaneously\n* Optional HTTP → HTTPS redirection\n* Reads config dynamically\n* Auto-creates logs if missing\n* Configurable via `.conf` file or CLI arguments\n* Threaded server for concurrent requests\n* Interactive terminal output is preserved\n\n---\n\n## Directory Structure\n\n```\ncustom-https-server/\n├── custom-https-server/\n│   ├── custom-https-server.service       # systemd unit file (Linux)\n│   ├── custom_https_server.py            # Main HTTP/HTTPS server script\n│   ├── default-config.conf               # Default configuration (path/port/SSL)\n│   ├── install.sh                        # Installer script (Linux \u0026 macOS)\n│   ├── macos-launchd-setup.sh            # macOS launchd agent setup\n│   ├── uninstall.sh                      # Uninstaller script\n│   └── update-service.sh                 # Update macOS plist / Linux systemd runtime args\n├── .ignore                               # Ignore file\n├── HTTPS_Server.jpeg                     # Screenshot / demo image\n├── LICENSE                               # MIT License\n└── README.md                             # Project documentation\n```\n\n---\n\n## 🐧 Linux Installation (Systemd Service)\n\n```bash\ngit clone https://github.com/kumarmuthu/custom-https-server.git\ncd custom-https-server/custom-https-server\nchmod +x install.sh uninstall.sh update-service.sh\nsudo ./install.sh\n\n# Install with virtualenv\nsudo ./install.sh -venv true\n\n# OR install using system python\nsudo ./install.sh -venv false\n```\n\n### Install with custom path and port\n\n```bash\nsudo ./install.sh -path /root -port 8080\n```\n\n\u003e 🛡️ **Note:** `sudo` is required for system paths like `/opt` or `/usr/local`.\n\n---\n\n### 🔧 Configure Port, Directory, and SSL\n\nEdit the config file:\n\nLinux:\n```bash\nsudo vi /etc/custom-https-server.conf\n```\n\nMac:\n```bash\nsudo vi /usr/local/etc/custom-https-server.conf\n```\n\n## ✅ Configuration File Check (`custom-https-server.conf`)\n\n```ini\n# -------------------------------\n# Generic server\n# -------------------------------\nSERVE_PATH=/root\nSERVE_PORT=8080\nMODE=read\n\n# -------------------------------\n# OS-specific overrides (optional)\n# -------------------------------\nLINUX_SERVE_PATH=/var/www\nMAC_SERVE_PATH=/Users/Shared\n\n# -------------------------------\n# Auth\n# -------------------------------\nAUTH_USERNAME=admin\nAUTH_PASSWORD=password\n\n# -------------------------------\n# Logs\n# -------------------------------\nCFG_LOG_DIR=dynamic_path\nCFG_LOG_FILE=dynamic_log_file\nCFG_ERR_FILE=dynamic_err_file\n```\n\n### How this config is interpreted\n\n* `SERVE_PATH`\n  → Default serve directory\n  → Overridden by `LINUX_SERVE_PATH` or `MAC_SERVE_PATH` automatically based on OS\n\n* `SERVE_PORT`\n  → Primary HTTP port\n  → Used **only via config** when running as a service\n\n* `MODE=read | write`\n  → Controls UI capabilities (explained below)\n\n* `CFG_LOG_*`\n  → Resolved dynamically at runtime\n  → Logs are auto-created if paths don’t exist\n\n\u003e Logs are auto-created if missing (`LOG_DIR`, `LOG_FILE`, `ERR_FILE`) and **stdout/stderr are displayed in terminal**\n\u003e when running interactively.\n\n---\n\nRestart to apply changes:\n\n```bash\nsudo systemctl restart custom-https-server\n```\n\n---\n\n### ✅ Verify\n\n```bash\nsudo systemctl status custom-https-server\nsudo lsof -i :80    # Or HTTP / HTTPS port from config\nsudo lsof -i :443   # Or HTTP / HTTPS port from config\nsudo lsof -i :8080  # Or HTTP / HTTPS port from config\n```\n\n---\n\n### 📜 Logs\n\nThe server **auto-creates logs** in the user directory (`LOG_DIR`) if missing. Example:\n\n```bash\ntail -f /home/\u003cusername\u003e/custom_https_server_log/logs/custom_https_server.log\ntail -f /home/\u003cusername\u003e/custom_https_server_log/logs/custom_https_server.err\n```\n\n\u003e Replace `\u003cusername\u003e` with your actual user.\n\n---\n\n### 🔓 Allow Port in Firewall (Linux)\n\nThe firewall configuration depends on your Linux distribution.\n\n---\n\n#### 🟥 Rocky / Alma / CentOS / RHEL (firewalld)\n\n```bash\nsudo firewall-cmd --permanent --add-port=80/tcp\nsudo firewall-cmd --permanent --add-port=443/tcp\nsudo firewall-cmd --permanent --add-port=8080/tcp\nsudo firewall-cmd --reload\n```\n\nVerify:\n\n```bash\nsudo firewall-cmd --list-ports\n```\n\n---\n\n#### 🟧 Ubuntu / Debian (UFW – recommended)\n\n```bash\nsudo ufw allow 80/tcp\nsudo ufw allow 443/tcp\nsudo ufw allow 8080/tcp\nsudo ufw reload\n```\n\nVerify:\n\n```bash\nsudo ufw status\n```\n\n---\n\n#### 🟦 Generic Linux (iptables – immediate but NOT persistent)\n\n```bash\nsudo iptables -I INPUT 1 -p tcp --dport 8080 -m conntrack --ctstate NEW -j ACCEPT\n```\n\nVerify:\n\n```bash\nsudo iptables -L INPUT -n --line-numbers\n```\n\n⚠️ **Important:**\nThis rule will be **lost after reboot** unless persistence is enabled.\n\nTo make it persistent on Ubuntu/Debian:\n\n```bash\nsudo apt install iptables-persistent\nsudo netfilter-persistent save\nsudo netfilter-persistent reload\n```\n\n---\n\n### 📝 Notes\n\n* Use **UFW** on Ubuntu whenever possible\n* Use **firewalld** on RHEL-based systems\n* Use raw **iptables** only for testing or minimal systems\n* If you change `SERVE_PORT`, update the firewall rule accordingly\n\n---\n\n### ❌ Uninstall (Linux)\n\n```bash\ncd custom-https-server/custom-https-server\nsudo ./uninstall.sh\n```\n\n---\n\n---\n\n## 🍏 macOS Installation (launchd Agent)\n\n```bash\ngit clone https://github.com/kumarmuthu/custom-https-server.git\ncd custom-https-server/custom-https-server\nchmod +x install.sh uninstall.sh macos-launchd-setup.sh update-service.sh\n```\n\nInstall with:\n\n```bash\nsudo ./install.sh -path /Users/\u003cusername\u003e -port 8080\n```\n\n* `-path` → Directory to serve\n* `-port` → HTTP/HTTPS port\n\nThe installer automatically sets up a `launchd` agent.\n\n---\n\n### ✅ Verify \u0026 Logs (macOS)\n\nCheck if service is running:\n\n```bash\nlaunchctl list | grep custom_https_server\n```\n\nValidate plist syntax (optional):\n\n```bash\nplutil ~/Library/LaunchAgents/com.custom_https_server.plist\n```\n\nWatch logs in real time:\n\n```bash\ntail -f /Users/\u003cusername\u003e/custom_https_server_log/logs/custom_https_server.log\ntail -f /Users/\u003cusername\u003e/custom_https_server_log/logs/custom_https_server.err\n```\n\n\u003e Replace `\u003cusername\u003e` with your actual macOS username.\n\n---\n\n### ❌ Uninstall (macOS)\n\n**Automated:**\n\n```bash\ncd custom-https-server/custom-https-server\nsudo ./uninstall.sh\n```\n\n**Manual:**\n\n```bash\nlaunchctl unload ~/Library/LaunchAgents/com.custom_https_server.plist\nrm -f ~/Library/LaunchAgents/com.custom_https_server.plist\nlaunchctl list | grep custom_https_server\n```\n\n---\n\n---\n\n## ✅ CLI Usage (Standalone / Development Mode)\n\n```bash\npython3 custom_https_server.py \\\n    --path /Users/muthukumar \\\n    --bind 0.0.0.0 \\\n    --mode read \\\n    --user admin \\\n    --pass password\n```\n\n### Behavior in CLI mode\n\n* **Ports are automatically loaded from the configuration file**\n* If no config file exists, **internal defaults are used**\n* CLI arguments **override config values only when explicitly provided**\n* Intended for:\n\n    * Development\n    * Debugging\n    * Temporary/manual runs\n* **Not used by systemd or launchd**\n\n---\n\n## ⚙️ Configuration \u0026 Port Handling (Important)\n\n\u003e **Important:**\n\u003e When running as a **systemd service (Linux)** or a **launchd agent (macOS)**, the server is started **without any CLI\narguments**.\n\nIn service mode:\n\n* No `--port`, `--path`, or other CLI flags are passed\n* All runtime settings are loaded dynamically from:\n\n  ```\n  /usr/local/etc/custom-https-server.conf or /etc/custom-https-server.conf\n  ```\n* This includes:\n\n    * HTTP / HTTPS ports\n    * Serve path (with OS overrides)\n    * Authentication credentials\n    * SSL certificate and key (if enabled)\n    * `read` / `write` mode\n\n👉 **CLI arguments are ignored in service mode by design**\n\n👉 They exist **only for standalone or development usage**\n\n---\n\n## 🔐 Server Modes: `read` vs `write`\n\nThe server supports **two operating modes** that control **UI behavior and filesystem access**.\nYou can configure the mode **during installation**, **via config file**, or **at runtime using CLI arguments**.\n\n---\n\n### 📘 READ Mode (Safe / View-Only)\n\n`MODE=read`\n\nThis is the **default and recommended mode** for logs, reports, artifacts, and internal documentation.\n\n**Behavior:**\n\n* ❌ No upload buttons\n* ❌ No delete buttons\n* ❌ No file selection checkboxes\n* ❌ No JavaScript console errors\n* ✅ Clean, static browsing UI\n* ✅ Breadcrumb navigation works\n* ✅ File search works\n* ✅ Sorting by name / size / date works\n* ✅ Read-only access to files and directories\n\n**Use cases:**\n\n* Test results\n* Logs\n* Build artifacts\n* Documentation servers\n* CI/CD output sharing\n* Audit-safe environments\n\n**Example config:**\n\n```ini\nMODE=read\n```\n\n**CLI example:**\n\n```bash\npython3 custom_https_server.py --mode read\n```\n\n---\n\n### ✍️ WRITE Mode (Full File Management UI)\n\n`MODE=write`\n\nEnables the **full interactive UI** with filesystem modification support.\n\n**Behavior:**\n\n* ✅ Upload files (with progress)\n* ✅ Delete files and directories\n* ✅ Select-all / multi-select support\n* ✅ Clean separation of HTML + JavaScript\n* ✅ No inline JS hacks\n* ✅ Full UI controls enabled\n* ⚠️ Filesystem is writable — use with care\n\n**UI Features Enabled:**\n\n* Upload button\n* Delete button\n* Progress bar\n* File checkboxes\n* Bulk operations\n\n**Use cases:**\n\n* Temporary file drops\n* Internal file sharing\n* Controlled admin environments\n* Dev / test systems\n\n**Example config:**\n\n```ini\nMODE=write\n```\n\n**CLI example:**\n\n```bash\npython3 custom_https_server.py --mode write\n```\n\n---\n\n### ⚠️ Security Recommendation\n\n* Use **`read` mode** for:\n\n    * Production\n    * CI systems\n    * Public or semi-public access\n* Use **`write` mode** only when:\n\n    * Authentication is enabled\n    * Access is restricted\n    * You trust all users\n\n\u003e The server intentionally keeps **read mode completely free of write-related UI elements and JS**, ensuring a clean,\n\u003e stable browsing experience.\n\n---\n\n## 🔄 Changing Mode After Installation\n\nThe server mode (`read` / `write`) is controlled **only via the config file**.\nAfter changing the config, **always reload using `update-service.sh`**.\n\n---\n\n## 🐧 Linux (systemd)\n\n### 1️⃣ Edit config\n\n```bash\nsudo vi /etc/custom-https-server.conf\n```\n\nChange:\n\n```ini\nMODE=read   # or write\n```\n\n### 2️⃣ Apply changes (recommended)\n\n```bash\nsudo ./update-service.sh\n```\n\n✅ What this does internally:\n\n* Stops the systemd service\n* Waits for the port to be released\n* Force-kills stale processes if needed\n* Updates `ExecStart`\n* Reloads systemd\n* Restarts the service cleanly\n\n\u003e ⚠️ **Do NOT use `systemctl restart` directly** after config changes —\n\u003e it may fail if the port is still in use.\n\n---\n\n## 🍏 macOS (launchd)\n\n### 1️⃣ Edit config\n\n```bash\nsudo vi /usr/local/etc/custom-https-server.conf\n```\n\nChange:\n\n```ini\nMODE=read   # or write\n```\n\n### 2️⃣ Apply changes (required on modern macOS)\n\n```bash\nsudo ./update-service.sh\n```\n\n✅ What this does internally:\n\n* Updates `ProgramArguments` in the plist\n* Disables `KeepAlive` temporarily\n* Properly `bootout`s the LaunchAgent\n* Kills lingering processes (user/root)\n* Waits for the port to fully free\n* Re-enables `KeepAlive`\n* `bootstrap`s the agent **as the original GUI user**\n\n---\n\n## ❌ Deprecated / NOT Recommended\n\n### macOS (old method)\n\n```bash\nlaunchctl unload ~/Library/LaunchAgents/com.custom_https_server.plist\nlaunchctl load ~/Library/LaunchAgents/com.custom_https_server.plist\n```\n\n🚫 Problems:\n\n* Breaks when run as root\n* Fails on Ventura+\n* Leaves zombie processes\n* Port conflict issues\n\n---\n\n## ✅ Final Recommendation (Both OS)\n\n**Always use this after changing config:**\n\n```bash\nsudo ./update-service.sh\n```\n\nThis guarantees:\n\n* No port conflicts\n* No zombie processes\n* Correct user context\n* Safe restart on both macOS \u0026 Linux\n\n---\n\n### ✅ Summary\n\n| Mode  | UI      | Upload | Delete | Safe for Prod |\n|-------|---------|--------|--------|---------------|\n| read  | Minimal | ❌      | ❌      | ✅             |\n| write | Full UI | ✅      | ✅      | ⚠️            |\n\n---\n\n### 📸 Screenshots\n\nThe following image gives you a glimpse of the application's interface:\n\n- **HTTPS Web Page**: ![HTTPS Web Page](HTTPS_Server.jpeg)\n\n---\n\n## License\n\nMIT License — free to use, modify, and distribute.\n\n---\n\n## Author\n\nDeveloped and maintained by **Muthukumar S**\nGitHub: [https://github.com/kumarmuthu](https://github.com/kumarmuthu)\n\n---\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkumarmuthu%2Fcustom-https-server","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkumarmuthu%2Fcustom-https-server","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkumarmuthu%2Fcustom-https-server/lists"}