Merge ~suligap/canonical-identity-provider:update-readme-setup-instructions into canonical-identity-provider:master

[Przemysław Suliga]

Update the initial setup section of the README

More information on how to setup the container and removal of some
outdated conflicting information.

[Hasan Ammar (hasanammar)]

Thanks for updating the instructions! If the instructions are similar enough, it may remove duplication to just point the user to: https://wiki.canonical.com/engineering/SnapStore/ContainerSetup (snapdevicegw README is a good example).

[Przemysław Suliga (suligap)]

Thanks Hasan. The wiki is private though. Are you aware of a public equivalent?

And now I realize that my change also links to the wiki, but more as "additional information".

[Hasan Ammar (hasanammar)]

Ah; in that case its probably a good idea to just have the updated instructions directly in the README. Thanks!

review: Approve

[Daniel Manrique (roadmr)]

+1 let's merge this.

review: Approve

diff --git a/README b/README
index a9701df..873e2b7 100644
--- a/README
+++ b/README
@@ -5,30 +5,65 @@ Development environment setup
 Getting started
 ===============
 
-The supported way to develop Canonical Identity Provider is using LXC.
-There's some additional documentation on LXC gotchas in the following
-page (check there specially if you can't resolve the LXC address when
-ssh'ing and if you want to open GUI apps seeing them in your host machine):
+0. The supported way to develop canonical-identity-provider is using Linux
+   containers via LXD.
 
-   https://wiki.canonical.com/UbuntuOne/Developer/LXC
+To get started, make sure you have LXD installed and ready to use on the host
+computer::
 
-To get started, make sure you have LXC installed and ready to use on
-the host computer::
+   $ sudo snap install lxd
 
-   $ sudo apt-get install libvirt-bin lxc
+After doing this, you can either logout and log back in, or use newgrp in your
+current shell session to switch to the lxd group::
 
-Once it's installed, the current supported version of Ubuntu is Trusty 14.04.
+   $ newgrp lxd
+
+A bare LXD container is completely isolated from the host; for development
+convenience, it is recommended to configure the container to:
+
+  - Mount your home directory from the host into the container. This allows you
+    to use your local configuration.
+  - Allow SSH without password, which may work once you mount your home if your
+    SSH configuration allows the host's key; if not, adding an
+    explicitly-allowed key might be necessary.
+  - Add your username to the container so you don't need to switch users when
+    using it.
+  - Map your UID from the host to the same one in the container, so files can
+    be written in the container without conflicts.
+
+If you are unsure on how to achieve all this, this script does the above, and
+it can be run verbatim or taken as a starting point to configure your
+container:
+
+https://gist.github.com/bloodearnest/ebf044476e70c4baee59c5000a10f4c8
+
+You can also see here if you have questions, want to know more about some
+possible LXD setups, or have some unusual configuration that might need
+adjusting the LXD profile:
+
+https://wiki.canonical.com/UbuntuOne/Developer/LXC#Installation_.28LXD.29
+
+Once LXD is installed, the current supported version of Ubuntu is Xenial 16.04.
 We'll create a new container specifically for this project to isolate it from
 the system and other projects::
 
-   $ lxc launch ubuntu:xenial sso-xenial
+   $ lxc launch ubuntu:16.04 -p default -p $USER sso-xenial
+
+Once it's up, log in (use SSH in forwarding mode so your host's keys apply and
+you can e.g. ``git clone`` from Launchpad without problems)::
 
-Once it's created, let's log in with your existing credentials::
+   $ ssh -A $SSO_XENIAL_CONTAINER_IP
 
-   $ ssh -A sso-xenial
+.. note::
 
-From now on, instructions will assume you're inside the sso-xenial LXC, unless
-otherwise noted.
+    There are several ways to obtain a suitable IP or hostname to connect via
+    SSH.  The easiest is to do `lxc list` and note the IP address assigned to
+    the container.  Other options provide consistent "hostnames" which are
+    easier to use but more involved to set up. See the wiki page referenced
+    above for some pointers on how to set this up.
+
+From now on, instructions will assume you're inside the sso-xenial container,
+unless otherwise noted.
 
 1. Get the code
 
@@ -41,13 +76,15 @@ otherwise noted.
     $ git clone lp:canonical-identity-provider
     $ cd canonical-identity-provider
 
-To set the prerequisites up inside the container, you can run the setup-container script
-with sudo (needed to install packages and change system config inside the container)::
 
-    $ sudo ./setup-container
+To set the prerequisites up inside the container, you can run the
+setup-container script with sudo (needed to install packages and change system
+config inside the container)::
+
+   $ sudo ./setup-container
 
-If you run into trouble or want to perform one or more steps manually, have a look at the
-setup-container script, which is quite simple and commented.
+If you run into trouble or want to perform one or more steps manually, have a
+look at the setup-container script.
 
 
 2. Bootstrap the project