Skip to content
Selfhost your Emacs and access it in browser
Shell Dockerfile
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.
asEnvUser Make ownership checks less aggressive Sep 14, 2019
compose Compose instructions Sep 12, 2019
docker-compose.example.yml add comment about .spacemacs and warning about mapping disks Sep 14, 2019

Docker Cloud Build Status

Docker hub

For ages I've been seeking a decent browser frontend for my org-mode notes and todo lists. Until I realised that nothing prevents me from having emacs itself in my browser.

Selfhost your Emacs with your favorite configuration.

Demo screenshot


Since I've became hooked on emacs, I've been looking for ways to have same experience in my browser. Sometimes you have to use non-personal computers where it's not possible/undesirable to install desktop Emacs and Dropbox/Syncthing to access your personal data. So I've been looking for some cloud solution since I've got a VPS.

The closest tool to what I wanted was Filestash: it suports vim/emacs bindings and some org-mode goodies. However, it wasn't anywhere as convenient as emacs.

Dropbox is not capable of previewing arbitrary text files let alone edit; and even if it could you obviously wouldn't get anything close to your usual emacs workflow.

And you could imagine that while elisp/vim style editing is fairly application agnostic, it's a thankless job to rewrire/port all the amazing emacs packages and features I'm used to like neotree, helm, refile, swoop, agenda, projectile, org-drill etc.

So I figured the only thing that would keep me happy is to run emacs itself over the web! Thankfully, due to its TUI interface that works surprisingly well.

It works really well with spacemacs style SPC/, bindings because they for the most part don't overlap with OS/browser hotkeys.

Try it out locally

  1. cp docker-compose.example.yml docker-compose.yml
  2. Edit necessary variables in docker-compose.yml, presumably your want to
    • map the files you want to make accessible to container
    • map the path to your config files/directories (e.g. .emacs.d or .spacemacs/.spacemacs.d). Also check the 'Setting up Spacemacs' section!
    • change port (see 'selfhost' secion)
  3. Run the container: ./compose up -d.
  4. Check it out in browser: 'http://localhost:8080'.

Setting up Spacemacs

Spacemacs doesn't use init.el, instead you have ~/.spacemacs.d directory, and ~/.emacs.d serves as Spacemacs distribution. I don't recommend you to reuse ~/.emacs.d your OS emacs distribution will generally be different from containers, and who knows what else could it break. Instead just clone spacemacs in a separate dir and map it.

On your Host OS:

git clone -b develop ~/.cloudmacs.d
cd ~/.cloudmacs.d && git revert --no-edit 5d4b80 # get around

In your docker-compose.yml, add:

      - ${HOME}/.cloudmacs.d:/home/emacs/.emacs.d


Some packages need extra binaries in the container (e.g. magit needs git). There are to ways you can deal with it

  1. Extend cloudmacs dockerfile and mix in the packages you need: see my example, where I'm extending the container with git and ripgrep. Then you can build it, e.g.:

    docker build -f Dockerfile.customized -t customized-cloudmacs --build-arg RIPGREP_VERSION="11.0.2" .

    Don't forget to update docker-compose.yml with the name of your new container.

  2. Install packages directly on running container. The downside is that it's easy to lose changes if you delete the container. Unfortunately docker-compose file doesn't support post-start scripts so if you want to automate this perhaps easiest would be to write a wrapper script like this:

    #!/bin/bash -eux
    docker-compose up -d
    docker exec cloudmacs sh -c "apk add --no-cache git"


  • I use basic auth to access my container.
  • Set up reverse proxy to access Gotty. Steps may vary depending on your web server, but for my nginx it looks like that:
    location / {
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $remote_addr;
        proxy_set_header Host $host;
        proxy_http_version 1.1;
        proxy_pass http://localhost:8888;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";

Potential improvements

  • split rg/locales/gotty in separate docker containers? maybe locales could be somehow moved to original emacs container?
    • also, after splitting it would be easy to make setup more generic and let people run vim/neovim, since the setup is pretty editor agnostic


  • Mobile phones -- you'd struggle to use default emacs/spacemacs on touchscreens. Perhaps there is some special phone friendly config out there? Anyway, I tend to use orgzly on my Android phone.



GPL due to the fact that I looked at other GPL licensed dockerfiles as reference.

You can’t perform that action at this time.