spacemacs/layers/+distributions/spacemacs-docker/README.org

spacemacs-docker distribution

• Description
  • Screenshots
  • Major benefits
• How to setup
• How to use
  • MacOS
  • Windows
  • GNU/Linux
  • With Xpra on any of the OSes and via web-browser
    • Pros
    • Cons
    • Instruction
      • With Xpra desktop client
      • Via web-browser
• Some basic docker commands to get you going

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.

Screenshots

MacOS

HD MacOS image

GNU/Linux

HD GNU/Linux image

Windows

HD Windows image

Major benefits

• Automatically get Spacemacs layers dependency installed with installer scripts
• Reap the benefit of Emacs and other GNU/Linux tools on Windows/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
• An easy way to swap Emacs version (emacs25 emacs-snapshot) for debugging
• 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.

How to setup

The idea is to build your own image FROM the one of the provided base images (spacemacs/emacs25 and spacemacs/emacs-snapshot). 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.

How to use

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

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 \
  spacemacs/emacs25

source, another method

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 \
 -e DISPLAY="unix$DISPLAY" \
 -v <path_to_your_workspace>:/mnt/workspace \
 spacemacs/emacs25

Or with -ti via winpty

winpty docker run -ti --name spacemacs \
 -e DISPLAY="unix$DISPLAY" \
 -v <path_to_your_workspace>:/mnt/workspace \
 spacemacs/emacs25

source Also You can use @ninrod 's vagrant setup

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 \
  spacemacs/emacs25

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`

source

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

Pros

• Xpra has a client for GNU/Linux, Windows and MacOS + 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 (O_O) demo

Cons

• Lag spikes with some OSes

Instruction

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

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/me.pub \
  -e DISPLAY=:14 \
  jare/x11-bridge

 docker run -ti --rm --name spacemacs \
  --volumes-from x11-bridge \
  -e DISPLAY=:14 \
  -e TZ=<your_time_zone> \
  spacemacs/emacs25

Now you can connect to it with Xpra desktop client

 <XPRA EXECUTABLE> attach --encoding=rgb \
  --ssh="ssh -o StrictHostKeyChecking=no -p 22" \
  ssh:xpra@localhost:14

Via web-browser

 docker run -ti --rm --name x11-bridge \
  -e MODE="html" \
  --net=host \
  -e XPRA_PASSWORD=<PASSWORD> \
  -e DISPLAY=:14 \
  jare/x11-bridge

 docker run -ti --rm --name spacemacs \
  --volumes-from x11-bridge \
  -e TZ=<your_time_zone> \
  -e DISPLAY=:14 \
  spacemacs/emacs25

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

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/emacs25 - remove spacemacs/emacs25 image
• docker pull spacemacs/emacs25 - get newer spacemacs/emacs25 version
• docker images -a - list all images
• docker ps -a - list all containers
• docker run ... spacemacs/emacs25 - run the default command
• docker run -ti ... spacemacs/emacs25 /bin/bash - start bash
• 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/emacs25
  • docker run ... -v my-ws:/home/developer/workspace ... jare/vim-bundle