Table of Contents

spacemacs-docker distribution

Table of ContentsClose

1 Description

Spacemacs distribution that aims to automate dependency installation for Spacemacs layers and provide well tested Docker based development environment with GUI support on all major platforms and even your web browser.

1.1 Features:

  • Automatically get Spacemacs layers dependency installed with installer scripts
  • Reap the benefit of Emacs and other GNU/Linux tools on Windows or macOS machines
  • Use docker hub to auto-build your environment and store full backups for free
  • Build once and work with the same development environment everywhere
  • Run untrusted/risky code in the tunable sandbox with CPU/network/disk quotas
  • Try new tools, experiment and roll back changes when something goes wrong
  • Share your setup with others or extend someone else's development environment
  • Run multiple Emacs instances on the same machine isolated
  • pause container to free resources temporarily
  • Checkpoint & Restore - maybe the fastest way to start a "heavy" environment
  • Friendly for networks with low upload speed/quotas.

2 Screenshots

3 How to setup

The idea is to build your own image FROM the one of provided base images. Get docker for the OS of the machine that will run development environment and then use spacemacs-docker-seed as an example to create automated builds on Docker Hub or build it locally.

4 How to use

With one of the methods below replace spacemacs/develop with your images. NOTE: The guide assumes that you want to run Docker and connect to it from the same machine.

4.1 macOS

Get XQuartz and open -a XQuartz In the XQuartz preferences go to the "Security" tab and make sure you've got "Allow connections from network clients" ticked

ip=$(ifconfig en0 | grep inet | awk '$1=="inet" {print $2}')
xhost + $ip
docker run -ti --name spacemacs \
 -e DISPLAY=$ip:0 \
 -e TZ=<your_time_zone> \
 -v <path_to_your_workspace>:/mnt/workspace \

source, another method

4.2 Windows

Get Cygwin with xinit, xorg-server and optionaly winpty (to run Emacs container with -t)

export DISPLAY=<your-machine-ip>:0.0
startxwin -- -listen tcp &
xhost + <your-machine-ip>
docker run --name spacemacs \
 -v <path_to_your_workspace>:/mnt/workspace \

Or with -ti via winpty

winpty docker run -ti --name spacemacs \
 -v <path_to_your_workspace>:/mnt/workspace \

source Also You can use @ninrod 's setup

4.3 GNU/Linux

Make sure that $DISPLAY variable is set

docker run -ti --name spacemacs \
 -e DISPLAY="unix$DISPLAY" \
 -e UNAME="spacemacser" \
 -e UID="1000" \
 -e TZ=<your_time_zone> \
 -v /tmp/.X11-unix:/tmp/.X11-unix:ro \
 -v /etc/localtime:/etc/localtime:ro \
 -v /etc/machine-id:/etc/machine-id:ro \
 -v /var/run/dbus:/var/run/dbus \
 -v <path_to_your_workspace>:/mnt/workspace \

UID and preferably UNAME should match the host's user id. You can set them in your Dockerfile with ENV statements. That's it! Now you should see Emacs window. But if it doesn't work You may need to allow local connection for the user

xhost +si:localuser:<UNAME>

Or allow local connection from the container's host-name

xhost +local:`docker inspect --format='{{ .Config.Hostname }}' spacemacs`


4.4 With Xpra on any of the OSes and via web-browser

4.4.1 Pros

  • Xpra has a client for GNU/Linux, Windows and macOS and can work via web browser
  • Persistent server (you can connect and disconnect without disrupting Emacs)
  • Interactive screen sharing demo
  • Read/write rss/email with Emacs in web-browser (OO) demo

4.4.2 Cons

  • Lag spikes with some OSes

4.4.3 Instruction

It's a good idea to read docker-x11-bridge and Xpra documentations, but here is a short instruction:

  1. With Xpra desktop client

    Get Xpra client for your OS. then

    docker run -ti --rm --name x11-bridge \
     -e MODE="ssh" \
     --net=host \
     -v ~/.ssh/pub_rsa:/etc/pub-keys/ \
     -e DISPLAY=:14 \
    docker run -ti --rm --name spacemacs \
     --volumes-from x11-bridge \
     -e DISPLAY=:14 \
     -e TZ=<your_time_zone> \

    Now you can connect to it with Xpra desktop client

    <XPRA EXECUTABLE> attach --encoding=rgb \
     --ssh="ssh -o StrictHostKeyChecking=no -p 22" \
  2. Via web-browser
    docker run -ti --rm --name x11-bridge \
     -e MODE="html" \
     --net=host \
     -e DISPLAY=:14 \
    docker run -ti --rm --name spacemacs \
     --volumes-from x11-bridge \
     -e TZ=<your_time_zone> \
     -e DISPLAY=:14 \

    Now visit http://localhost:10000/index.html?encoding=png&password =<PASSWORD>

5 Some basic docker commands to get you going

  • docker rm -f spacemacs - remove spacemacs container
  • docker restart spacemacs - restart spacemacs container
  • docker rmi -f spacemacs/develop - remove spacemacs/develop image
  • docker pull spacemacs/develop - get newer spacemacs/develop version
  • docker images -a - list all images
  • docker ps -a - list all containers
  • docker run ... spacemacs/develop - run default cmd
  • docker run -ti ... spacemacs/develop /bin/bash - start bash
  • docker run --network=host ... - less overhead and no need to map ports
  • docker exec spacemacs /usr/bin/emacs - start /usr/bin/emacs

With the running spacemacs container

  • docker logs spacemacs - print spacemacs container's logs
  • docker cp <from_local_path> spacemacs:/<to_my_spacemacs_container_path>
  • docker cp spacemacs:/<from_my_spacemacs_container_path> <to_local_path>
  • Manage data in containers with Docker volumes. Example
    • docker volume create --name my-ws
    • docker run ... -v my-ws:/mnt/workspace ... spacemacs/develop
    • docker run ... -v my-ws:/home/developer/workspace ... jare/vim-bundle

Author: root

Created: 2019-11-10 Sun 14:17