docs: add notes on snap build and publish
License: MIT Signed-off-by: Oli Evans <oli@tableflip.io>
Oli Evans committed
Oct 12, 2020 at 18:13 UTC
f69b067ed36ecb2a8fae85ce6d7b019d64fa8bb8
1 file changed
+201
docs/snap.md
new
+201
@@ -0,0 +1,201 @@
1
+# Publishing go-ipfs as a snap
2
+
3
+> Snap is the default package manager for ubuntu since the release of 20.04. This doc captures what we know about building go-ipfs as a snap packge and publishing it to the snapstore.
4
+
5
+The go-ipfs snap is defined in [snap/snapcraft.yaml](https://github.com/ipfs/go-ipfs/blob/master/snap/snapcraft.yaml). For more detail on our snapcraft.yaml see: https://github.com/ipfs-shipyard/ipfs-snap
6
+
7
+- go-ipfs is published as `ipfs` to the snapcraft store, see: https://snapcraft.io/ipfs
8
+- ipfs-desktop is published as `ipfs-desktop`, from CI, here: https://github.com/ipfs-shipyard/ipfs-desktop/blob/master/.github/workflows/snapcraft.yml
9
+
10
+For go-ipfs we deliberately lean on the Canonical lauchpad.net build environment so as it simplifies creating builds for more architectures, which has been requested by user numerous times.
11
+
12
+Linux user can install go-ipfs with:
13
+
14
+```
15
+$ snap install ipfs
16
+```
17
+
18
+Apps installed via Snapcraft are auto-updating by default. Snapcraft uses 'Release Channels' to let the user pick their stability level, with channels for `stable`, `candidate`, `beta` and `edge`. Snap will install the lasest release from the `stable` channel by default. A user that wants to test out the bleeding edge can opt in by passing the `--edge` flag
19
+
20
+```
21
+$ snap install --edge ipfs
22
+```
23
+
24
+<img width="1072" alt="Dashboard for managaing go-ipfs snap release channels for go-ipfs" src="https://user-images.githubusercontent.com/58871/95761096-bcb34580-0ca3-11eb-8ce7-2496b2456335.png">
25
+
26
+## Known issues
27
+
28
+- `ipfs mount` fails as fusermount is not included in the snap, and cannot work from a snap as it is not able to create non-root mounts, see: https://github.com/elopio/ipfs-snap/issues/6
29
+
30
+```console
31
+ubuntu@primary:~$ ipfs mount
32
+2020-07-10T09:54:17.458+0100 ERROR node node/mount_unix.go:91 error mounting: fusermount: exec: "fusermount": executable file not found in $PATH
33
+2020-07-10T09:54:17.463+0100 ERROR node node/mount_unix.go:95 error mounting: fusermount: exec: "fusermount": executable file not found in $PATH
34
+```
35
+
36
+## Developing
37
+
38
+We let launchpad.net build our snap for us, but if you need to edit the snapcraft.yml you can test it locally
39
+
40
+### Requirements
41
+
42
+ You need `snapcraft` installed locally
43
+
44
+```console
45
+# ubuntu or similar
46
+$ snap install snapcraft --classic
47
+
48
+# macos
49
+$ brew install snapcraft
50
+```
51
+
52
+### Build and test
53
+
54
+**Build** out a snap package for go-ipfs by running the following from this project
55
+
56
+```console
57
+$ snapcraft
58
+```
59
+
60
+**Test** the built snap package by installing it on a system that has `snapd`
61
+
62
+```
63
+$ snap install ipfs_<snap details here>.snap
64
+# then kick the tires
65
+$ ubuntu@primary:~$ ipfs daemon
66
+Initializing daemon...
67
+go-ipfs version: 0.7.0-dev
68
+```
69
+
70
+You can test it out on mac too. By installing and using `snapcraft`, it'll pull in `multipass` which is a quick way to run an ubuntu vm, and it has a notion of a primary container, which gets nice things like automounting your home dir in the vm, so you can:
71
+
72
+```console
73
+# install your .snap in a multipass vm
74
+$ multipass shell
75
+ubuntu@primary:~$ cd ~/Home/path/to/snap/on/host/filesystem
76
+ubuntu@primary:~$ snap install ipfs_<snap details>.snap --devmode --dangerous
77
+ubuntu@primary:~$ ipfs daemon
78
+Initializing daemon...
79
+go-ipfs version: 0.7.0-dev
80
+```
81
+
82
+### Building in Docker
83
+
84
+[ipfs-shipyard/ipfs-snap](https://github.com/ipfs-shipyard/ipfs-snap) includes a Dockerfile that creates an image that can build go-ipfs from source and package it as a snap. It starts with `snapcore/snapcraft:stable` and adds in `go` and just enough tools to allow snapcraft to build go-ipfs. It is published to dockerhub as `ipfs/ipfs-snap-builder`.
85
+
86
+```console
87
+$ docker run -v $(pwd):/my-snap ipfs/ipfs-snap-builder:latest sh -c "apt update && cd /my-snap && snapcraft --debug"
88
+```
89
+
90
+## Publishing the Snap
91
+
92
+The following snap release channels are published automatically:
93
+
94
+| Git branch | Snap channel |
95
+|------------|--------------|
96
+| `release` | `stable`
97
+| `master` | `edge`
98
+
99
+
100
+### Edge via snapcraft.io
101
+
102
+The snapcraft store watches the default branch of the go-ipfs repo, and updates the snap for the `edge` channel. This service is configured automatically by snapcraft. It's neat, but it doesn't allow us to watch any branch other than the default.
103
+
104
+<img width="1072" alt="Screenshot 2020-10-12 at 15 56 07" src="https://user-images.githubusercontent.com/58871/95761075-b755fb00-0ca3-11eb-99d4-95e5f42cb48a.png">
105
+
106
+
107
+### Stable via launchpad.net
108
+
109
+The `stable` channel is published automatically via launchpad.net. There is a mirror of the go-ipfs repo at https://launchpad.net/go-ipfs that is sync'd with the github repo every few hours (at canonical's leisure).
110
+
111
+A snap build configuration called `ipfs-stable` is set up to watch the `release` branch on go-ipfs and publish it to the `stable` snap channel.
112
+
113
+The key configuration points are:
114
+
115
+```yaml
116
+# What flavour VM to build on.
117
+Series: infer from snapcraft.yml
118
+
119
+Source:
120
+ Git:
121
+ # the launchpad mirror of go-ipfs
122
+ Git repository: ~ipfs/go-ipfs/+git/go-ipfs
123
+ Git branch: refs/heads/release
124
+
125
+Automatically build when branch changes: true
126
+ Source snap channels for automatic builds:
127
+ # tell snapcraft what version of snapcraft to use when building.
128
+ # NOTE: At time of writing we use the default `core18` platform for the
129
+ # go-ipfs snap. If you specify others here, a build error occurs, which
130
+ # I think is mainly due to a launchpad ux bug here.
131
+ core: ""
132
+ core18: stable
133
+ core20: ""
134
+ snapcraft: stable
135
+
136
+
137
+Automatically upload to store:
138
+ Registered store package name: ipfs
139
+ Store channels:
140
+ Risk:
141
+ Stable: true
142
+
143
+# What architectures to build for. this selection is chosen to match the auto
144
+# configured build provided by snapcraft for the edge channel, for neatness, so
145
+# that all architectures that currently have builds in snap continue to get
146
+# updates, even though some of them would be tough for use to test on.
147
+Processors:
148
+ amd64: true
149
+ # raspi 4
150
+ arm64: true
151
+ # older raspi
152
+ armhf: true
153
+ # sure ok i guess.
154
+ i386: true
155
+ # hmmm... PowerPC!?
156
+ ppc64el: true
157
+ # wat. IBM system Z mainframes!?
158
+ s390x: true
159
+```
160
+
161
+
162
+
163
+### Future work - Publish RCs to the `candidate` channel
164
+
165
+If we wish to publish release candidates to the snap store, we can do that by creating a new snap build config
166
+
167
+1. Find the `release-vX.X` branch in the lauchpad.net mirror of the go-ipfs repo.
168
+ - e.g. https://code.launchpad.net/~ipfs/go-ipfs/+git/go-ipfs/+ref/release-v0.7.0
169
+2. Click "Create snap package"
170
+3. Fill out the form using the same values as listed above for the stable channel, but:
171
+ - Set `Name` to `ipfs-candidate` _(this just needs to be a unique name to identify this config)_
172
+ - For `Risk` select only `Candidate` _(so the snap is published to the `Candidate` channel.)_
173
+
174
+You can trigger a build manually to kick things off. Subsequent changes to that branch will be published as a snap automatically when when the mirror next syncs with github (every 6-12hrs)
175
+
176
+
177
+## Who can edit this?
178
+
179
+The `ipfs` snapcraft.io listing can be edited by
180
+
181
+- @elopio _TBC, the original submitter, need to check about getting ownership transferred._
182
+- @lidel
183
+- @olizilla
184
+
185
+You need a Canonical developer account, then ask an existing owner to add you. Accsess is managed here https://dashboard.snapcraft.io/snaps/ipfs/collaboration/
186
+
187
+
188
+The launchpad.net config is managed by [**IPFS Maintainers**](https://launchpad.net/~ipfs) team, and you can request to join that team with your Canonical developer acccount. The list of maintainers is here: https://launchpad.net/~ipfs/+members
189
+
190
+At the time of writing the launchpad maintainers are:
191
+
192
+- @lidel
193
+- @olizilla
194
+
195
+
196
+## References
197
+
198
+- Walkthrough of publishing a snap package via snapcraft and launchpad: https://www.youtube.com/watch?v=X_U-pcvBFrU
199
+- For more details on the go-ipfs snapcraft.yaml see: https://github.com/ipfs-shipyard/ipfs-snap
200
+- publishing to multiple channels via build.snapcraft.io: https://forum.snapcraft.io/t/maintaining-and-publishing-multiple-to-multiple-channels-via-build-snapcraft-io/12455
201
+- How node.js manages snaps: https://github.com/ipfs/go-ipfs/issues/7679#issuecomment-695914986