- [[#i-have-a-lagpicture-is-blurryclipboard-sharing-doesnt-work][I have a lag/picture is blurry/clipboard sharing doesn't work...]]
- [[#ranger-sometimes-lags-with-the-message--process--something-][Ranger sometimes lags with the message "... process ... something ..."]]
- [[#localize-the-bug-current-status-heisenbug-][localize the bug. Current status: heisenbug :(]]
- [[#sometimesrarely-i-have-strange-emacs-slowdowns][Sometimes(rarely) I have strange Emacs slowdowns]]
- [[#find-out-whats-going-one][Find out what's going one.]]
* Description
Cross-platform, cross-device persistent emacs distribution with
automatic dependency management and free cloud builds/backups.
* Features:
1) automatic dependency(SDK, tools) installation for Spacemacs layers. Instead
of everyone figuring out how to install/build a layer dependencies, we can
write an installation script once and everyone will automatically get them.
2) Run the same Spacemacs installation across all platforms and devices
separately or shared (useful for mentoring, collaborative editing etc.)
[[https://i.imgur.com/ijdSuX6.gifv][DEMO]] - same Spacemacs instance shared between Win 10 Notebook and Ubuntu PC.
On the both systems Spacemacs window(frame) behaves like if it was a native
app it even has proper taskbar icon :) Copy-pasta and full-screen also work.
You can even use Spacemacs in a web-browser! ([[https://i.imgur.com/wDLDMZN.gifv][DEMO]])
It us useful, for example, if you want to showcase Spacemacs or your personal
setup with the zero install requirements.
3) Client can disconnect and reconnect(from the same or another machine) to
a Spacemacs instance without disturbing its execution. [[https://i.imgur.com/3FLISud.gifv][DEMO]].
It means that you can start Spacemacs at work and simply connect to it from
a handheld devices on the way back home to check rss feed/email and then
from a home machine and Spacemacs will be in the exact same state as you
left it.
4) You can run multiply Spacemacs instances on the same host. [[https://i.imgur.com/v6xeBtW.gifv][DEMO]].
They can be fully isolated or share only what you want them to share.
Bandwidth, CPU, disk space quota also supported. It may be really useful
for education. Imagine a classroom with a bunch of cheap Raspberry PI
clients and one Spacemacs host(local or cloud based).
5) Pausing(freezing) - may be handy if you want to temporary free CPU
resources, but don't want to kill your development environment.
6) Snapshots for host migration and potentially the fastest way to start
Spacemacs based development environment, especially if you use stuff like
JVM that needs time to "heat up" [[https://i.imgur.com/plTjTXL.gifv][DEMO]]. For GNU/Linux it uses native
"snapshoter" [[https://criu.org/Main_Page][CRIU]]
7) Disposable sandboxed development environment. Its much harder to damager
your actual OS and if your experiment gone wrong you can drop all changes.
8) Free cloud builds and storage - especially handy if your internet upload is
much slower or expensive than download.
9) Since spacemacs-docker distribution uses common base (Emacs version, OS,
packages) it is much easer to reproduce and fix bugs.
10) Docker uses [[https://docs.docker.com/engine/userguide/storagedriver/imagesandcontainers/][layered filesystem]] so for updates you'll need to download only
the changed layer. Also you can make multiply images that share the most of
data so they require less disk space.
* Drawbacks:
1) While performance with the GNU/Linux host seems to be equal(perceptually)
to a locally installed Spacemacs, even with a Windows 10 client on a fairly
ancient laptop(first gen. mobile i3). It's actual better, if you take into
account code linter, compiler etc.). But if you host both client and server
on such laptop you'll experience noticeable keyboard lag (probably due to
low specs and a poor Hyper-V support).
2) You will need Docker on the server machine and(for the most cases) Xpra
at the client + ssh. But if you don't mind some hacks and want to use Linux
and run spacemacs-docker locally, then you only need Docker. As a bonus
you'll get max speed.
* Getting started(AFTER THIS PR IS MERGED)
** For all platform
*** How to build:
- Install docker like [[https://docker.github.io/engine/installation/][normal ppl do]] or
[[https://get.docker.com/][like if there is no tomorrow(don't forget sudo)]].
Also you'll need [[https://xpra.org][Xpra]] (optionally).
- Fork [[https://github.com/JAremko/spacemacs-docker-seed][the seed repo]], read its [[https://github.com/JAremko/spacemacs-docker-seed/blob/master/README.md][README.org]]
- Register at [[https://hub.docker.com/][DockeHub]] and create an [[https://docs.docker.com/docker-hub/builds/][automated builds]] from the fork.
Also you may want to link it to =spacemacs/onbuild= repository - this way
your Spacemacs will automatically rebuild each time =spacemacs/onbuild= is
updated.
*** How to use(with the default settings)
**** Xpra over SSH(GUI):
- =docker run -ti --rm -p 22:22 <YOU_NAME>/spacemacs= it will attach Xpra
output to the console, it you detach it Docker will kill and delete the
container (and all changes). So to make it useful you need to mount your
workspace. To do so add =-v <...>/workspace:/mnt/workspace= where =<...>=
is the absolute path to your local workspace. Also you probably would like
to make your layouts and recent files persistent:
First create a folder on the host's file system where you want to store
those files. For example =/tmp/spacemacs-cache= then =docker run= with
It will make =spacemacs-docker= setup much less "beginner friendly".
Currently user's .spacemacs file serves similar role. During the
build process(at DockerHub) builder reads .spacemacs file and reads
layer related variables from Spacemacs to configures the installation
or even modify the .spacemacs file.
If will be impossible to do with the modular design. Also modularity
may increase the maintenance cost of the distribution.
** Why Xpra?
- Besides all the Xpra features outlined in the [[#features][Features]] section.
It also has a client for all major platforms (even Android) and
due to its implementation it is likely to work in the same way
with all the client variations, so it should be easier to maintain.
** How to update?
- First get a new version =docker pull <YOUR_NAME>/spacemacs=
- Then run it. And if it is fine, remove the old one:
1) Get image list =docker images=.
2) Remove an image =docker rmi <IMAGE>=.
** How to get an older build(backup) of my Spacemacs?
You can [[https://docs.docker.com/engine/reference/commandline/pull/#/pull-an-image-by-digest-immutable-identifier][pull by the digest]]. Also you can use digest in the =FROM=
Dockerfile instruction.
** TODO Add answers to the questions from the PR
* Troubleshooting
** Font size/screen is messed-up. Help!
If you have more than one display/projector or other displaying
device connected, Xpra may use DPI from the wrong device. You can
specify DPI at the client with =xpra attach --dpi=<DPI> ...= and/or
at the server side. [[https://github.com/JAremko/spacemacs-docker-seed/blob/master/Dockerfile#L33][See Seed project's Dockerfile]].
** Mosh fonts/space-line doesn't look right
You probably need to install =NanumGothic= and =source-code-pro= fonts
** I have a lag/picture is blurry/clipboard sharing doesn't work...
Xpra has many setting that can be changed on the fly(some of them have
hot-keys). While attached, click Xpra logo near the system clock on the
taskbar(Windows) and make sure that the configs are right.
** Ranger sometimes lags with the message "... process ... something ..."
*** TODO localize the bug. Current status: heisenbug :(
** Sometimes(rarely) I have strange Emacs slowdowns