aboutsummaryrefslogtreecommitdiff
path: root/DOCUMENTATION.md
blob: 1697299e34025ffb8d8a407b42a667a62c6cf362 (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
Get Started
===========

- You may run ./nixops/scripts/setup to setup the directory and variables
  The script won’t do anything without asking first, you may stop at any
  step.

Nix snippets
============

- Evaluate nixos build:
  `nix eval -f '<nixpkgs/nixos>' options.virtualisation.anbox.image.value.outPath`

Helpers / External documentation
================================

- How to write good options in a module (not too much to ensure it’s maintainable, ...):
  https://github.com/NixOS/rfcs/blob/e719102ace17c2b4a8b98efe0f08e344a7713dec/rfcs/0042-config-option.md
- SSL configuration: https://ssl-config.mozilla.org/
  And check: https://www.ssllabs.com/

Channels
========

- [channel](https://nixos.org/channels/nixos-20.03)
- nixpkgs-unstable: last version of nixpkgs
- nixos-unstable: last one guaranteed to build a correct system

The LDAP directory
==================

The LDAP directory has been hand-tuned and may not have the same layout
as "regular" LDAP directories.

Sections
--------
The directory is divided in several sections:
- The "service" section (ou=services,dc=immae,dc=eu) contains all the
  services. Each service usually has a list of dn (can be real user or
  hosts or anything) that can access it. Conversely, a service usually
  cannot list users he doesn’t have access to.
- The "hosts" section (ou=hosts,dc=immae,dc=eu) contains the identities
  of hosts. They tend to be less used now. But sometimes they need to
  have an identity (mostly to be able to send e-mails) The subsection
  "roles" (ou=roles,ou=hosts,dc=immae,dc=eu) was from a Puppet age and
  is deprecated. Only one host remains handled by Puppet (caldance) and
  should be replaced with an internal VM.
- The "groups" section (ou=groups,dc=immae,dc=eu) contains the generic
  groups of users not associated to a service.
- The "group_users" and "users" sections contain the users (usually with
  password) of the infrastructure. The "users" section usally contains a
  single "physical" person, while the "group_user" represents a shared
  identity (plus one legacy "buildbot" system identity).

How does nixpkgs resolve
========================

To build nixops machines
------------------------

The `NIX_PATH` environment variable is built in nixops/Makefile and
contains three paths: nixpkgs, nixpkgsNext, nixpkgsPrevious. Only the
first one is actually used most of the time. Derivations that need
pinned nixpkgs should declare it in `nix/sources.json` (it’s the case
for some buildbot scripts for instance).

The config and overlays in standard directories will be read
(~/.config/nixpkgs) and parsed, but should not have any consequence on
the result.

In shells
---------

When calling nix tools from shells, the environment variable `NIX_PATH`
will determine the `<nixpkgs>` version that will be used. In addition,
`~/.config/nixpkgs/overlays.nix` will add an overlay to this nixpkgs. In
its current state, it resolves to
    builtins.attrValues (import "${thisRepository}/overlays")

To build Home-manager
---------------------

Home-manager will use the same mechanisms as the shell and use the
configuration from ~/.config/nixpkgs/home.nix . In the current state,
pkgs will refer to the `<nixpkgs>` content, that is nixos-unstable
channel. The exception is `home.packages` (which will populate
~/.nix-profile), which is built partly by importing the
`myEnvironments.immae-eu.packages` key of this repository’s
`default.nix`. This file uses the nix/sources.json "nixpkgs" key by
default, which may differ from `<nixpkgs>`.
Consistency needs to be ensured either by using nix/sources.json
everywhere or by using the unstable channel.
default.nix was changed to accept pkgs, making in effect use of the
unstable channel everywhere.

To build NUR
------------

The NUR bot will evaluate default.nix with `pkgs` argument set with its
own nixpkgs version. It will not permit fetching urls related to nixpkgs
during the evaluation.

HTTP
====

[Reference](https://infosec.mozilla.org/guidelines/web_security)
Protections that can be implemented:
- `Header always set Strict-Transport-Security "max-age=31536000"`
  Force https on this domain for the age duration
- Public-Key-Pins -> dangerous if acme private key changes
- Always load script/style by https (don’t use `//`)
- Content-Security-Policy
  Either as `<meta http-equiv="Content-Security-Policy" content="...">` (must be first one!)
  Or as Content-Security-Policy header
- Restrictive referrer status

Packaging issues
================

Yarn
----

- Sometimes yarn will silently ignore package.json: the build will succeed but output will be empty. In that case it means that some mandatory fields are missing (mainly: `name`, `version`)
- If yarn complains about `TypeError: Cannot read property 'lang' of undefined`:
  make sure that all package names in yarn-packages.nix finish in .tar.gz where due
- If yarn complains about `error Couldn't find the binary git`:
  It’s related to the previous error:
  - the initial yarn.lock and package.json contain some reference to github repositories.
  - They need to be changed to a fixed version, and the resolved url needs to point to a tar.gz file.
  - Example (the diff should be saved as a patch and applied to the yarn derivation build):
        --- a/package.json
        +++ b/package.json
        @@ -2,9 +2,9 @@
         	"name": "foo",
         	"private": true,
         	"dependencies": {
        -		"@danielfarrell/bootstrap-combobox": "https://github.com/berrnd/bootstrap-combobox.git#master",
        +		"@danielfarrell/bootstrap-combobox": "^1.1.8",
         		"@fortawesome/fontawesome-free": "^5.12.1",
         		"animate.css": "^3.7.2",
         		"bootbox": "^5.3.2",
         		"bootstrap": "^4.3.1",
        --- a/yarn.lock
        +++ b/yarn.lock
        @@ -2,18 +2,18 @@
         # yarn lockfile v1
        -"@danielfarrell/bootstrap-combobox@https://github.com/berrnd/bootstrap-combobox.git#master":
        +"@danielfarrell/bootstrap-combobox@^1.1.8":
           version "1.1.8"
        -  resolved "https://github.com/berrnd/bootstrap-combobox.git#fcf0110146f4daab94888234c57d198b4ca5f129"
        +  resolved "https://github.com/berrnd/bootstrap-combobox/archive/fcf0110146f4daab94888234c57d198b4ca5f129.tar.gz"
  - Also the yarn-packages.nix needs to be changed accordingly: the name of the package in that file needs to match the one computed by yarn2nix (special chars replaced with underscores), and the url needs to point to the correct url too
  - Example:
        --- a/yarn-packages.nix
        +++ b/yarn-packages.nix
        @@ -3,11 +3,11 @@
             {
        -      name = "https___github.com_berrnd_bootstrap_combobox.git";
        +      name = "https___github.com_berrnd_bootstrap_combobox_archive_fcf0110146f4daab94888234c57d198b4ca5f129.tar.gz";
               path = fetchurl {
        -        name = "https___github.com_berrnd_bootstrap_combobox.git";
        -        url  = "https://github.com/berrnd/bootstrap-combobox.git";
        -        sha1 = "fcf0110146f4daab94888234c57d198b4ca5f129";
        +        name = "https___github.com_berrnd_bootstrap_combobox_archive_fcf0110146f4daab94888234c57d198b4ca5f129.tar.gz";
        +        url  = "https://github.com/berrnd/bootstrap-combobox/archive/fcf0110146f4daab94888234c57d198b4ca5f129.tar.gz";
        +        sha1 = "0nvnkr1w9nnn7r2h63zmkjpphawwmfca";
               };
             }

NUR
===

[Link to the CI latest job](https://travis-ci.com/github/nix-community/NUR)

Upgrades
========

Things to look at during upgrades:

Upgrade to latest unstable
-------------------

- Nothing in particular yet

Etherpad-lite
-------------

When upgrading etherpad-lite modules, make sure that possible hacks are
carried along (usually as preBuild hook). Run the following command in
the module directory:

    node2nix -i node-packages.json

Nodejs
------

- The nodeHeaders will change at each bump, making previous hash
  incorrect (current at unstable: 1df3yhlwlvai0m9kvjyknjg11hnw0kj0rnhyzbwvsfjnmr6z8r76)
- At runtime, peertube may complain about mismatching NODE_MODULE_VERSION for bcrypt. Check the url to make sure that it contains the same module version:
  [](https://github.com/kelektiv/node.bcrypt.js/releases/download/v3.0.2/bcrypt_lib-v3.0.2-node-v64-linux-x64-glibc.tar.gz)
  change the v64 to whichever value corresponds in
  [](https://nodejs.org/en/download/releases/)

PHP/Mysql/PAM
-------------

adminer installation requires pam module (it’s the only one, since pam
is only used in php environment by "humans" account). It currently
doesn’t work, I couldn’t find a way to properly make php find the
mariadb include files. It seems like php74 might solve the issue
https://stackoverflow.com/questions/50026939/php-mysqli-connect-authentication-method-unknown-to-the-client-caching-sha2-pa

Postgresql
----------

Postgresql is linked to glibc version. Any change in this version may
corrupt the indexes:
[](https://wiki.postgresql.org/wiki/Locale_data_changes#What_to_do)

For postgresql major upgrade:
- Change the postgresql overlay to define `postgresql_next`
- import `modules/private/databases/postgresql_upgrade.nix` and adjust the header to mark the cluster to upgrade.
- Deploy it
- run `upgrade-pg-cluster` as root
- Add an overlay for the server:
  ```
  nixpkgs.overlays = [ (self: super: {
    postgresql = self.postgresql_next;
  }) ];
  ```
- Deploy (make sure that the new datadir is the one that gets used)
- If everyone has upgraded, the per-server overlay may be removed and
  the global one modified

Nextcloud
---------

- Do not skip major versions!
- Put nextcloud in maintenance mode :
  ```
  nextcloud-occ maintenance:mode --on
  ```
- Do a backup :
  ```
  sudo -u postgres pg_dump -n owncloud webapps > nextcloud.sql
  ```
- Upgrade
- Run the upgrade task :
  ```
  nextcloud-occ upgrade
  ```
 - Stop maintenance mode :
  ```
  nextcloud-occ maintenance:mode --off
  ```
- Issues :
  https://docs.nextcloud.com/server/16/admin_manual/maintenance/manual_upgrade.html