{"id":21018015,"url":"https://github.com/sthysel/butterfly-nginx","last_synced_at":"2026-04-21T21:03:46.345Z","repository":{"id":56627399,"uuid":"93919690","full_name":"sthysel/butterfly-nginx","owner":"sthysel","description":"Butterfly behind nginx","archived":false,"fork":false,"pushed_at":"2020-10-28T01:28:09.000Z","size":100,"stargazers_count":3,"open_issues_count":0,"forks_count":1,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-03-11T04:59:45.837Z","etag":null,"topics":["butterfly","encryption","nginx","shell"],"latest_commit_sha":null,"homepage":null,"language":null,"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/sthysel.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}},"created_at":"2017-06-10T06:11:48.000Z","updated_at":"2021-09-22T05:17:41.000Z","dependencies_parsed_at":"2022-08-15T22:10:51.997Z","dependency_job_id":null,"html_url":"https://github.com/sthysel/butterfly-nginx","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sthysel%2Fbutterfly-nginx","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sthysel%2Fbutterfly-nginx/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sthysel%2Fbutterfly-nginx/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sthysel%2Fbutterfly-nginx/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sthysel","download_url":"https://codeload.github.com/sthysel/butterfly-nginx/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243447641,"owners_count":20292452,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":["butterfly","encryption","nginx","shell"],"created_at":"2024-11-19T10:23:09.547Z","updated_at":"2025-12-29T21:04:56.967Z","avatar_url":"https://github.com/sthysel.png","language":null,"funding_links":[],"categories":[],"sub_categories":[],"readme":"# butterfly-nginx\n\n![](./docs/butterfly.png)\n\nInstall butterfly terminal emulator behind a Let's Encrypt cert secured nginx proxy.\n\nTo register with Let's Encrypt use nginx's default setup with the webroot plugin. Once that is done\nuse the server config detailed below, which also includes the webroot setup, to serve\nbutterfly.\n\n# Prerequisites\n\n* Ubuntu 16.04 or later server \n* You must own or control the registered domain name that you wish to use the\n  certificate with. Make use of any of the many domain name registars. There must be a\n  A Record that points your domain to the public IP address of your server.\n\nRecipe follows, be sure to substitute ```docker.sthysel.net``` with the correct\ndomain name.\n\n## Install nginx \n\n```bash\n$ sudo apt-get install nginx\n```\n\nEdit /etc/nginx/sites-available/default to include the .well_known location for the \nwebroot plugin that 'Lets Encrypt' will use to verify that you control the domain you\nwant the cert for.\n\n\n```\nserver {\n        listen 80 default_server;\n        listen [::]:80 default_server;\n\n\n        root /var/www/html;\n\n        index index.html index.htm index.nginx-debian.html;\n\n        server_name _;\n\n        location / {\n                # First attempt to serve request as file, then\n                # as directory, then fall back to displaying a 404.\n                try_files $uri $uri/ =404;\n        }\n\n       location ~ /.well-known {\n                allow all;\n        }\n}\n```\n\nTest with ```$ sudo nginx -t``` and restart ```$ sudo systemctl restart nginx```\n\n## Install certbot\n\n```bash\n$ sudo add-apt-repository ppa:certbot/certbot\n$ sudo apt-get update\n$ sudo apt-get install certbot\n```\n\nMint the certificate.\n\n```bash\n$ sudo certbot certonly --webroot --webroot-path=/var/www/html -d docker.sthysel.net\n```\n\nThey appear here:\n\n```bash\nINSERT  thys@dockerhost   ~  sudo tree /etc/letsencrypt/live  \n[sudo] password for thys: \n/etc/letsencrypt/live\n└── docker.sthysel.net\n    ├── cert.pem -\u003e ../../archive/docker.sthysel.net/cert1.pem\n    ├── chain.pem -\u003e ../../archive/docker.sthysel.net/chain1.pem\n    ├── fullchain.pem -\u003e ../../archive/docker.sthysel.net/fullchain1.pem\n    ├── privkey.pem -\u003e ../../archive/docker.sthysel.net/privkey1.pem\n    └── README\n``` \n\nThe butterfly nginx config will use those certs.\n\n### Generate Strong Diffie-Hellman Group \n\nTo further increase security, you should also generate a strong Diffie-Hellman\ngroup. To generate a 2048-bit group, use this command:\n\n```bash\n$ sudo openssl dhparam -out /etc/ssl/certs/dhparam.pem 2048 \n```\n\nThis may take a few minutes but when it's done you will have a strong DH group at\n```/etc/ssl/certs/dhparam.pem.```\n\n\n## nginx snippets for encrypted connections\n\nIn ```/etc/nginx/snippets/ssl-params.conf```\n\n```\n# from https://cipherli.st/\n# and https://raymii.org/s/tutorials/Strong_SSL_Security_On_nginx.html\n\nssl_protocols TLSv1 TLSv1.1 TLSv1.2;\nssl_prefer_server_ciphers on;\nssl_ciphers \"EECDH+AESGCM:EDH+AESGCM:AES256+EECDH:AES256+EDH\";\n\nssl_ecdh_curve secp384r1;\nssl_session_cache shared:SSL:10m;\nssl_session_tickets off;\nssl_stapling on;\nssl_stapling_verify on;\nresolver 8.8.8.8 8.8.4.4 valid=300s;\nresolver_timeout 5s;\n# disable HSTS header for now\n#add_header Strict-Transport-Security \"max-age=63072000; includeSubDomains; preload\";\nadd_header X-Frame-Options DENY;\nadd_header X-Content-Type-Options nosniff;\n\nssl_dhparam /etc/ssl/certs/dhparam.pem;\n\n```\n\n\nIn ```/etc/nginx/snippets/ssl-docker.sthysel.net.conf```\n\n```\nssl_certificate /etc/letsencrypt/live/docker.sthysel.net/fullchain.pem;\nssl_certificate_key /etc/letsencrypt/live/docker.sthysel.net/privkey.pem;\n```\n\n\n## Install butterly \n\nInstall in nginx docroot, for this config its in ```/var/www/html```\n\n\n``` bash\n$ sudo bash\n$ mkdir -p /var/www/butterfly\n$ cd /var/www/butterfly\n$ virtualenv -p python3 venv\n$ source venv/bin/activate\n$ pip install butterfly\n$ pip install libsass\n$ deactivate\n$ exit\n```\n\nButterfly needs to run always so add a systemd service to make that happen\n\nIn ```/etc/systemd/system/butterfly.service``` \n\n```\n\n[Unit]\nDescription=Butterfly service\nAfter=network.target\n\n[Service]\nExecStart=/var/www/butterfly/venv/bin/butterfly.server.py --unsecure --login=true --host=127.0.0.1\nRestart=always\nStandardOutput=syslog\nStandardError=syslog\nSyslogIdentifier=buttefly\n\n[Install]\nWantedBy=multi-user.target\n```\n\nStart and enable butterfly service.\n\n```bash\n$ sudo systemctl enable butterfly\n$ sudo systemctl start butterfly\n$ sudo systemctl status butterfly\n```\n\n## butterfly nginx config\n\nNow make a new butterfly nginx config using the snippets prepared earlier\n\nIn ```/etc/nginx/sites-available/butterfly```\n\n```\nserver {\n    listen       80;\n    listen       443 ssl;\n\n    listen       [::]:80;\n    listen       [::]:443 ssl;\n\n    server_name  docker.sthysel.net;\n\n    include snippets/ssl-docker.sthysel.net.conf;\n    include snippets/ssl-params.conf;\n\n\n    charset utf-8;\n\n    access_log  /var/log/nginx/$host.access.log;\n\n    client_max_body_size 20M;\n\n    root   /var/www/html/;\n    index  index.html index.htm;\n\n    if ($ssl_protocol = \"\") {\n        return 301 https://$http_host$request_uri;\n    }\n\n    location / {\n        try_files $uri $uri/ =404;\n    }\n\n    error_page   500 502 503 504  /50x.html;\n    location = /50x.html {\n        root   /usr/share/nginx/html;\n    }\n\n    location ~ /.well-known {\n         allow all;\n    }\n\n    location /butterfly {\n        auth_basic \"Authentication required\";\n        auth_basic_user_file /etc/nginx/.htpasswd;\n\n        rewrite ^/butterfly/?(.*) /$1 break;\n        proxy_pass http://127.0.0.1:57575;\n        proxy_http_version 1.1;\n        proxy_set_header Upgrade $http_upgrade;\n        proxy_set_header Connection \"upgrade\";\n        proxy_set_header Host $host;\n        proxy_set_header Origin \"$scheme://$host\";\n\n        proxy_connect_timeout 7d;                                                                                                              \n        proxy_send_timeout 7d;                                                                                                                 \n        proxy_read_timeout 7d;\n\n        sub_filter_once off;\n\n        sub_filter_types text/css text/xml application/javascript;\n        sub_filter /style.css '/butterfly/style.css';\n        sub_filter /static '/butterfly/static';\n        sub_filter /ws '/butterfly/ws';\n        sub_filter /ctl '/butterfly/ctl';\n        sub_filter /themes '/butterfly/themes';\n        sub_filter location.pathname '\"/\"';\n    }\n\n    rewrite ^/theme/?(.*)/butterfly/?(.*) /butterfly/theme/$1/$2 permanent;\n}\n\n```\n\n\nBe sure to make the file ```/var/log/nginx/docker.sthysel.net.access.log``` with the correct\npermissions. On Ubuntu its  ```www-data adm```.\n\n\n```/etc/nginx/.htpasswd``` is generate by htpasswd:\n\n```bash\n$ sudo htpasswd -c /etc/nginx/.htpasswd YOUR_HTTP_AUTH_USER_NAME\n```\n\nTest with ```$ sudo nginx -t``` and restart ```$ sudo systemctl restart nginx```\n\nNow hit butterfly at https://docker.sthysel.net/butterfly\n\n\n# Resources\n\n* https://www.digitalocean.com/community/tutorials/how-to-install-nginx-on-ubuntu-16-04\n* https://github.com/paradoxxxzero/butterfly/wiki/Butterfly-with-nginx-reverse-proxy-and-https\n* https://www.digitalocean.com/community/tutorials/how-to-secure-nginx-with-let-s-encrypt-on-ubuntu-16-04\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsthysel%2Fbutterfly-nginx","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsthysel%2Fbutterfly-nginx","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsthysel%2Fbutterfly-nginx/lists"}