Existing install: document copying over locale.conf
[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//branched/)
39 [direct link](https://kojipkgs.fedoraproject.org/compose//branched/Fedora-26-20170707.n.0/compose/Workstation/x86_64/iso/Fedora-Workstation-ostree-x86_64-26-20170707.n.0.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.
91 ```
92 ostree admin deploy --os=fedora --karg-proc-cmdline --karg=enforcing=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`.
101
102 You'll also need to copy your user entry from `/etc/passwd`, `/etc/group`,
103 and `/etc/shadow` into the new `/etc/`, and add yourself to the wheel group
104 in `/etc/group`. Don't copy just copy these files literally, however, since
105 the system users and groups won't be the same.
106
107 **For BIOS systems**: while ostree regenerated the bootloader configuration,
108 it writes config into `/boot/loader/grub.cfg`.  On a current `grubby`
109 system, you'll need to copy that version over:
110
111 ```
112 cp /boot/loader/grub.cfg /boot/grub2/grub.cfg
113 ```
114
115 Migrating between OSTree repos
116 -------------------------------------
117
118 Enable the 26/27 remotes:
119 ```
120 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
121 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
122 ```
123 Rebase to rawhide:
124 ```
125 rpm-ostree rebase fedora-ws-27:fedora/rawhide/x86_64/workstation
126 ```
127  
128 Using the system
129 --------------------
130
131 First, try out `rpm-ostree install` to layer additional packages.  For example,
132 `rpm-ostree install powerline`.
133
134 Next, let's try flatpak. Before you do: There's a known flatpak issue on
135 AtomicWS - run [this workaround](https://github.com/flatpak/flatpak/issues/113#issuecomment-247022006),
136 which you only need to do once. After that, [try flatpak](http://flatpak.org/apps.html).
137
138 If you are a developer for server applications,
139 try [oc cluster up](https://github.com/openshift/origin/blob/master/docs/cluster_up_down.md) to
140 create a local OpenShift v3 cluster.
141
142 Finally, you'll likely want to make one or more "pet" Docker containers,
143 potentially privileged, and use `dnf/yum` inside these. You can use e.g. `-v
144 /srv:/srv` so these containers can share content with your host (such as git
145 repositories). Note that if you want to share content between multiple Docker
146 containers and the host (e.g. your desktop session), you should execute (once):
147
148 ```
149 sudo chcon -R -h -t container_file_t /var/srv
150 ```
151
152 Future work
153 -----------
154
155  - GNOME Software support for both rpm-ostree/flatpak and possibly docker
156  - automated tests that run on this content