Merge #54 `README.md: fix link to side-by-side install doc`
[workstation-ostree-config.git] / README.md
1 For some background, see:
2
3  - https://fedoraproject.org/wiki/Workstation/AtomicWorkstation
4  - https://fedoraproject.org/wiki/Changes/WorkstationOstree
5  
6 (Note also this repo obsoletes https://pagure.io/atomic-ws)
7
8 High level design
9 -----------------
10
11 The goal of the system is to be a workstation, using
12 rpm-ostree for the base OS, and a combination of
13 Docker and Flatpak containers, as well as virtualization
14 tools such as Vagrant.
15
16 Status
17 ------
18
19 This project is actively maintained and is ready for use
20 by sophisticated and interested users, but not ready
21 for widespread promotion.
22
23 See some [https://lists.fedoraproject.org/archives/list/desktop@lists.fedoraproject.org/thread/J6BJS7Z4NKNOQUZWGYXZZIEKYMWBBSUY/](discussion about the first release).
24
25 Installing
26 ------------
27
28 There are ISOs available for [Fedora 27](https://dl.fedoraproject.org/pub/fedora/linux/releases/27/WorkstationOstree/x86_64/iso/).
29
30 Alternatively, see a guide for [installing inside an existing system](https://pagure.io/workstation-ostree-config/blob/master/f/README-install-inside.md).
31
32 Important issues:
33 -----------------------
34
35  - [flatpak system repo](https://github.com/flatpak/flatpak/issues/113#issuecomment-247022006)
36
37 Using the system
38 --------------------
39
40 One of the first things you should do use is use a container runtime of your
41 choice to manage one or more "pet" containers.  This is where you will use
42 `yum/dnf` to install utilities.
43
44 With `docker` for example, you can use the `-v /srv:/srv` command line option so
45 these containers can share content with your host (such as git repositories).
46 Note that if you want to share content between multiple Docker containers and
47 the host (e.g. your desktop session), you should execute (once):
48
49 ```
50 sudo chcon -R -h -t container_file_t /var/srv
51 ```
52
53 Next, let's try flatpak. Before you do: There's a known flatpak issue on
54 AtomicWS - run [this workaround](https://github.com/flatpak/flatpak/issues/113#issuecomment-247022006),
55 which you only need to do once. After that, [try flatpak](http://flatpak.org/apps.html).
56
57 If you are a developer for server applications,
58 try [oc cluster up](https://github.com/openshift/origin/blob/master/docs/cluster_up_down.md) to
59 create a local OpenShift v3 cluster.
60
61 Finally, try out `rpm-ostree install` to layer additional packages directly on
62 the host. This is needed for "host extensions" - privileged software that
63 doesn't make sense to live in a container. For example, `rpm-ostree install
64 powerline` to use that software for the shell prompts of the host.  Another
65 good example is `rpm-ostree install vagrant-libvirt` to use [Vagrant](https://www.vagrantup.com/)
66 to manage VMs.
67
68 Future work
69 -----------
70
71  - GNOME Software support for both rpm-ostree/flatpak and possibly docker
72  - automated tests that run on this content