README.md: minor fixes and touch-ups
[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 Updates not currently generated for Fedora 26
24 --------------------------------------------------------
25
26 If you choose Fedora 26, note that Fedora is not currently
27 shipping updates.  For that, see [atomic-ws](https://pagure.io/atomic-ws).
28
29 Installing (do not use partitioning defaults!)
30 ----------
31
32 Important!  *Don't* choose auto-partitioning in the below installer ISO; you
33 currently can't use a separate `/home` partition, and Anaconda defaults to that.
34 This will be fixed in Fedora 27; see
35 this [known issue](https://bugzilla.redhat.com/show_bug.cgi?id=1382873) as
36 well as [this anaconda PR](https://github.com/rhinstaller/anaconda/pull/1124).
37
38 There are ISOs available for [Fedora 26](https://kojipkgs.fedoraproject.org/compose/26/)
39 [direct link](https://kojipkgs.fedoraproject.org/compose//26/latest-Fedora-26/compose/Workstation/x86_64/iso/Fedora-Workstation-ostree-x86_64-26-1.5.iso)
40 and [rawhide](https://kojipkgs.fedoraproject.org/compose//rawhide/).
41
42 Important issues:
43 -----------------------
44
45  - [Anaconda autopartitoning](https://github.com/rhinstaller/anaconda/issues/800) - be sure to use `/var/home` instead of `/home`
46  - [flatpak system repo](https://github.com/flatpak/flatpak/issues/113#issuecomment-247022006)
47
48 Installing *inside* an existing system
49 ---------------------------------------
50
51 A really neat feature of OSTree is that you can
52 *parallel install* inside your existing OS.  Let's try that, we
53 first make sure we have the ostree packages:
54
55 ```
56 yum -y install ostree ostree-grub2
57 ```
58
59 Next, we add `/ostree/repo` to the filesystem:
60 ```
61 ostree admin init-fs /
62 ```
63
64 Add a remote which points to the Fedora Rawhide content:
65 ```
66 ostree remote add --set=gpg-verify=false fedora-ws-rawhide https://kojipkgs.fedoraproject.org/compose/ostree/rawhide/
67 ```
68
69 Pull down the content (you can interrupt and restart this):
70 ```
71 ostree --repo=/ostree/repo pull fedora-ws-rawhide:fedora/rawhide/x86_64/workstation
72 ```
73
74 Initialize an "os" for this, which acts as a state root.
75 ```
76 ostree admin os-init fedora
77 ```
78
79 **For EFI systems**: currently ostree uses the presence of /boot/grub2/grub.cfg to detect a BIOS system,
80 but that can be present on systems booted with EFI as well. If you boot with EFI
81 (/sys/firmware/efi exists), then you need to move /boot/grub2/grub.cfg aside:
82 ```
83 mv /boot/grub2/grub.cfg /boot/grub2/grub.cfg.bak
84 ```
85 Since this file is not used on a EFI system, this won't break the operation of your current system. While you are at it, back up your existing grub config:
86 ```
87 cp /boot/efi/EFI/fedora/grub.cfg /boot/efi/EFI/fedora/grub.cfg.bak
88 ```
89
90 Deploy; we use `enforcing=0` to avoid SELinux issues for now, and --karg=rghb=0 to avoid a hang with Plymouth (these aren't needed if deploying Fedora 26 currently).
91 ```
92 ostree admin deploy --os=fedora --karg-proc-cmdline --karg=enforcing=0 --karg=rhgb=0 fedora-ws-rawhide:fedora/rawhide/x86_64/workstation
93 ```
94
95 To initialize this root, you'll need to copy over your `/etc/fstab`, `/etc/locale.conf`, `/etc/default/grub` at least, along with the ostree remote that we added:
96 ```
97 for i in /etc/fstab /etc/default/grub /etc/locale.conf /etc/ostree/remotes.d/fedora-ws-rawhide.conf ; do cp $i /ostree/deploy/fedora/deploy/$checksum.0/$i; done
98 ```
99 If you have a separate `/home` mount point, you'll need to change
100 that `fstab` copy to refer to `/var/home`. If you *don't* have a separate /home mount
101 point, then you need to make sure that a symlink will be created:
102 ```
103 echo 'L /var/home - - - - ../sysroot/home' > /ostree/deploy/fedora/deploy/$checksum.0/etc/tmpfiles.d/00rpm-ostree.conf
104 ```
105
106 You'll also need to copy your user entry from `/etc/passwd`, `/etc/group`,
107 and `/etc/shadow` into the new `/etc/`, and add yourself to the wheel group
108 in `/etc/group`. Don't copy just copy these files literally, however, since
109 the system users and groups won't be the same.
110
111 **For BIOS systems**: while ostree regenerated the bootloader configuration,
112 it writes config into `/boot/loader/grub.cfg`.  On a current `grubby`
113 system, you'll need to copy that version over:
114
115 ```
116 cp /boot/loader/grub.cfg /boot/grub2/grub.cfg
117 ```
118
119 Migrating between OSTree repos
120 -------------------------------------
121
122 Enable the 26/27 remotes:
123 ```
124 ostree remote add --if-not-exists --gpg-import /etc/pki/rpm-gpg/RPM-GPG-KEY-fedora-26-primary fedora-ws-26 https://kojipkgs.fedoraproject.org/compose/ostree/26
125 ostree remote add --if-not-exists --gpg-import /etc/pki/rpm-gpg/RPM-GPG-KEY-fedora-27-primary fedora-ws-27 https://kojipkgs.fedoraproject.org/compose/ostree/rawhide
126 ```
127 Rebase to rawhide:
128 ```
129 rpm-ostree rebase fedora-ws-27:fedora/rawhide/x86_64/workstation
130 ```
131  
132 Using the system
133 --------------------
134
135 First, try out `rpm-ostree install` to layer additional packages.  For example,
136 `rpm-ostree install powerline`.
137
138 Next, let's try flatpak. Before you do: There's a known flatpak issue on
139 AtomicWS - run [this workaround](https://github.com/flatpak/flatpak/issues/113#issuecomment-247022006),
140 which you only need to do once. After that, [try flatpak](http://flatpak.org/apps.html).
141
142 If you are a developer for server applications,
143 try [oc cluster up](https://github.com/openshift/origin/blob/master/docs/cluster_up_down.md) to
144 create a local OpenShift v3 cluster.
145
146 Finally, you'll likely want to make one or more "pet" Docker containers,
147 potentially privileged, and use `dnf/yum` inside these. You can use e.g. `-v
148 /srv:/srv` so these containers can share content with your host (such as git
149 repositories). Note that if you want to share content between multiple Docker
150 containers and the host (e.g. your desktop session), you should execute (once):
151
152 ```
153 sudo chcon -R -h -t container_file_t /var/srv
154 ```
155
156 Future work
157 -----------
158
159  - GNOME Software support for both rpm-ostree/flatpak and possibly docker
160  - automated tests that run on this content