support/doc/production.md

   1 # Production guide
   2
   3   * [Installation](#installation)
   4   * [Upgrade](#upgrade)
   5
   6 ## Installation
   7
   8 Please don't install PeerTube for production on a device behind a low bandwidth connection (example: your ADSL link).
   9 If you want information about the appropriate hardware to run PeerTube, please see the [FAQ](https://github.com/Chocobozzz/PeerTube/blob/develop/FAQ.md#should-i-have-a-big-server-to-run-peertube).
  10
  11 ### Dependencies
  12
  13 **Follow the steps of the [dependencies guide](dependencies.md).**
  14
  15 ### PeerTube user
  16
  17 Create a `peertube` user with `/var/www/peertube` home:
  18
  19 ```
  20 $ sudo useradd -m -d /var/www/peertube -s /bin/bash -p peertube peertube
  21 ```
  22
  23 Set its password:
  24 ```
  25 $ sudo passwd peertube
  26 ```
  27
  28 **On FreeBSD**
  29
  30 ```
  31 $ sudo pw useradd -n peertube -d /var/www/peertube -s /usr/local/bin/bash -m
  32 $ sudo passwd peertube
  33 ```
  34 or use `adduser` to create it interactively.
  35
  36 ### Database
  37
  38 Create the production database and a peertube user inside PostgreSQL:
  39
  40 ```
  41 $ sudo -u postgres createuser -P peertube
  42 ```
  43
  44 Here you should enter a password for postgresql user peertube, it should be copied in production.yaml file.
  45 Don’t just hit enter else it will be empty, default production yaml uses peertube here, but it is better you pick a stronger one.
  46
  47 ```
  48 $ sudo -u postgres createdb -O peertube -E UTF8 -T template0 peertube_prod
  49 ```
  50
  51
  52 Then enable extensions PeerTube needs:
  53
  54 ```
  55 $ sudo -u postgres psql -c "CREATE EXTENSION pg_trgm;" peertube_prod
  56 $ sudo -u postgres psql -c "CREATE EXTENSION unaccent;" peertube_prod
  57 ```
  58
  59 ### Prepare PeerTube directory
  60
  61 Fetch the latest tagged version of Peertube
  62 ```
  63 $ VERSION=$(curl -s https://api.github.com/repos/chocobozzz/peertube/releases/latest | grep tag_name | cut -d '"' -f 4) && echo "Latest Peertube version is $VERSION"
  64 ```
  65
  66 Open the peertube directory, create a few required directories
  67 ```
  68 $ cd /var/www/peertube
  69 $ sudo -u peertube mkdir config storage versions
  70 ```
  71
  72 Download the latest version of the Peertube client, unzip it and remove the zip
  73 ```
  74 $ cd /var/www/peertube/versions
  75 $ sudo -u peertube wget -q "https://github.com/Chocobozzz/PeerTube/releases/download/${VERSION}/peertube-${VERSION}.zip"
  76 $ sudo -u peertube unzip -q peertube-${VERSION}.zip && sudo -u peertube rm peertube-${VERSION}.zip
  77 ```
  78
  79 Install Peertube:
  80 ```
  81 $ cd /var/www/peertube
  82 $ sudo -u peertube ln -s versions/peertube-${VERSION} ./peertube-latest
  83 $ cd ./peertube-latest && sudo -H -u peertube yarn install --production --pure-lockfile
  84 ```
  85
  86 ### PeerTube configuration
  87
  88 Copy the default configuration file that contains the default configuration provided by PeerTube.
  89 You **must not** update this file.
  90
  91 ```
  92 $ cd /var/www/peertube
  93 $ sudo -u peertube cp peertube-latest/config/default.yaml config/default.yaml
  94 ```
  95
  96 Now copy the production example configuration:
  97
  98 ```
  99 $ cd /var/www/peertube
 100 $ sudo -u peertube cp peertube-latest/config/production.yaml.example config/production.yaml
 101 ```
 102
 103 Then edit the `config/production.yaml` file according to your webserver
 104 and database configuration (`webserver`, `database`, `redis`, `smtp` and `admin.email` sections in particular).
 105 Keys defined in `config/production.yaml` will override keys defined in `config/default.yaml`.
 106
 107 **PeerTube does not support webserver host change**. Even though [PeerTube CLI can help you to switch hostname](https://docs.joinpeertube.org/maintain-tools?id=update-hostjs) there's no official support for that since it is a risky operation that might result in unforeseen errors.
 108
 109 ### Webserver
 110
 111 We only provide official configuration files for Nginx.
 112
 113 Copy the nginx configuration template:
 114
 115 ```
 116 $ sudo cp /var/www/peertube/peertube-latest/support/nginx/peertube /etc/nginx/sites-available/peertube
 117 ```
 118
 119 Then set the domain for the webserver configuration file.
 120 Replace `[peertube-domain]` with the domain for the peertube server.
 121
 122 ```
 123 $ sudo sed -i 's/${WEBSERVER_HOST}/[peertube-domain]/g' /etc/nginx/sites-available/peertube
 124 $ sudo sed -i 's/${PEERTUBE_HOST}/127.0.0.1:9000/g' /etc/nginx/sites-available/peertube
 125 ```
 126
 127 Then modify the webserver configuration file. Please pay attention to the `alias` keys of the static locations.
 128 It should correspond to the paths of your storage directories (set in the configuration file inside the `storage` key).
 129
 130 ```
 131 $ sudo vim /etc/nginx/sites-available/peertube
 132 ```
 133
 134 Activate the configuration file:
 135
 136 ```
 137 $ sudo ln -s /etc/nginx/sites-available/peertube /etc/nginx/sites-enabled/peertube
 138 ```
 139
 140 To generate the certificate for your domain as required to make https work you can use [Let's Encrypt](https://letsencrypt.org/):
 141
 142 ```
 143 $ sudo systemctl stop nginx
 144 $ sudo certbot certonly --standalone --post-hook "systemctl restart nginx"
 145 $ sudo systemctl reload nginx
 146 ```
 147
 148 Now you have the certificates you can reload nginx:
 149
 150 ```
 151 $ sudo systemctl reload nginx
 152 ```
 153
 154 Certbot should have installed a cron to automatically renew your certificate.
 155 Since our nginx template supports webroot renewal, we suggest you to update the renewal config file to use the `webroot` authenticator:
 156
 157 ```
 158 $ # Replace authenticator = standalone by authenticator = webroot
 159 $ # Add webroot_path = /var/www/certbot
 160 $ sudo vim /etc/letsencrypt/renewal/your-domain.com.conf
 161 ```
 162
 163 **FreeBSD**
 164 On FreeBSD you can use [Dehydrated](https://dehydrated.io/) `security/dehydrated` for [Let's Encrypt](https://letsencrypt.org/)
 165
 166 ```
 167 $ sudo pkg install dehydrated
 168 ```
 169
 170 ### TCP/IP Tuning
 171
 172 **On Linux**
 173
 174 ```
 175 $ sudo cp /var/www/peertube/peertube-latest/support/sysctl.d/30-peertube-tcp.conf /etc/sysctl.d/
 176 $ sudo sysctl -p /etc/sysctl.d/30-peertube-tcp.conf
 177 ```
 178
 179 Your distro may enable this by default, but at least Debian 9 does not, and the default FIFO
 180 scheduler is quite prone to "Buffer Bloat" and extreme latency when dealing with slower client
 181 links as we often encounter in a video server.
 182
 183 ### systemd
 184
 185 If your OS uses systemd, copy the configuration template:
 186
 187 ```
 188 $ sudo cp /var/www/peertube/peertube-latest/support/systemd/peertube.service /etc/systemd/system/
 189 ```
 190
 191 Check the service file (PeerTube paths and security directives):
 192
 193 ```
 194 $ sudo vim /etc/systemd/system/peertube.service
 195 ```
 196
 197
 198 Tell systemd to reload its config:
 199
 200 ```
 201 $ sudo systemctl daemon-reload
 202 ```
 203
 204 If you want to start PeerTube on boot:
 205
 206 ```
 207 $ sudo systemctl enable peertube
 208 ```
 209
 210 Run:
 211
 212 ```
 213 $ sudo systemctl start peertube
 214 $ sudo journalctl -feu peertube
 215 ```
 216
 217 **FreeBSD**
 218 On FreeBSD, copy the startup script and update rc.conf:
 219
 220 ```
 221 $ sudo install -m 0555 /var/www/peertube/peertube-latest/support/freebsd/peertube /usr/local/etc/rc.d/
 222 $ sudo sysrc peertube_enable="YES"
 223 ```
 224
 225 Run:
 226
 227 ```
 228 $ sudo service peertube start
 229 ```
 230
 231 ### OpenRC
 232
 233 If your OS uses OpenRC, copy the service script:
 234
 235 ```
 236 $ sudo cp /var/www/peertube/peertube-latest/support/init.d/peertube /etc/init.d/
 237 ```
 238
 239 If you want to start PeerTube on boot:
 240
 241 ```
 242 $ sudo rc-update add peertube default
 243 ```
 244
 245 Run and print last logs:
 246
 247 ```
 248 $ sudo /etc/init.d/peertube start
 249 $ tail -f /var/log/peertube/peertube.log
 250 ```
 251
 252 ### Administrator
 253
 254 The administrator password is automatically generated and can be found in the PeerTube
 255 logs (path defined in `production.yaml`). You can also set another password with:
 256
 257 ```
 258 $ cd /var/www/peertube/peertube-latest && NODE_CONFIG_DIR=/var/www/peertube/config NODE_ENV=production npm run reset-password -- -u root
 259 ```
 260
 261 Alternatively you can set the environment variable `PT_INITIAL_ROOT_PASSWORD`,
 262 to your own administrator password, although it must be 6 characters or more.
 263
 264 ### What now?
 265
 266 Now your instance is up you can:
 267
 268  * Add your instance to the public PeerTube instances index if you want to: https://instances.joinpeertube.org/
 269  * Check [available CLI tools](/support/doc/tools.md)
 270
 271 ## Upgrade
 272
 273 ### PeerTube instance
 274
 275 **Check the changelog (in particular BREAKING CHANGES!):** https://github.com/Chocobozzz/PeerTube/blob/develop/CHANGELOG.md
 276
 277 #### Auto
 278
 279 The password it asks is PeerTube's database user password.
 280
 281 ```
 282 $ cd /var/www/peertube/peertube-latest/scripts && sudo -H -u peertube ./upgrade.sh
 283 ```
 284
 285 #### Manually
 286
 287 Make a SQL backup
 288
 289 ```
 290 $ SQL_BACKUP_PATH="backup/sql-peertube_prod-$(date -Im).bak" && \
 291     cd /var/www/peertube && sudo -u peertube mkdir -p backup && \
 292     sudo -u postgres pg_dump -F c peertube_prod | sudo -u peertube tee "$SQL_BACKUP_PATH" >/dev/null
 293 ```
 294
 295 Fetch the latest tagged version of Peertube:
 296
 297 ```
 298 $ VERSION=$(curl -s https://api.github.com/repos/chocobozzz/peertube/releases/latest | grep tag_name | cut -d '"' -f 4) && echo "Latest Peertube version is $VERSION"
 299 ```
 300
 301 Download the new version and unzip it:
 302
 303 ```
 304 $ cd /var/www/peertube/versions && \
 305     sudo -u peertube wget -q "https://github.com/Chocobozzz/PeerTube/releases/download/${VERSION}/peertube-${VERSION}.zip" && \
 306     sudo -u peertube unzip -o peertube-${VERSION}.zip && \
 307     sudo -u peertube rm peertube-${VERSION}.zip
 308 ```
 309
 310 Install node dependencies:
 311
 312 ```
 313 $ cd /var/www/peertube/versions/peertube-${VERSION} && \
 314     sudo -H -u peertube yarn install --production --pure-lockfile
 315 ```
 316
 317 Copy new configuration defaults values and update your configuration file:
 318
 319 ```
 320 $ sudo -u peertube cp /var/www/peertube/versions/peertube-${VERSION}/config/default.yaml /var/www/peertube/config/default.yaml
 321 $ diff /var/www/peertube/versions/peertube-${VERSION}/config/production.yaml.example /var/www/peertube/config/production.yaml
 322 ```
 323
 324 Change the link to point to the latest version:
 325
 326 ```
 327 $ cd /var/www/peertube && \
 328     sudo unlink ./peertube-latest && \
 329     sudo -u peertube ln -s versions/peertube-${VERSION} ./peertube-latest
 330 ```
 331
 332 ### nginx
 333
 334 Check changes in nginx configuration:
 335
 336 ```
 337 $ cd /var/www/peertube/versions
 338 $ diff "$(ls --sort=t | head -2 | tail -1)/support/nginx/peertube" "$(ls --sort=t | head -1)/support/nginx/peertube"
 339 ```
 340
 341 ### systemd
 342
 343 Check changes in systemd configuration:
 344
 345 ```
 346 $ cd /var/www/peertube/versions
 347 $ diff "$(ls --sort=t | head -2 | tail -1)/support/systemd/peertube.service" "$(ls --sort=t | head -1)/support/systemd/peertube.service"
 348 ```
 349
 350 ### Restart PeerTube
 351
 352 If you changed your nginx configuration:
 353
 354 ```
 355 $ sudo systemctl reload nginx
 356 ```
 357
 358 If you changed your systemd configuration:
 359
 360 ```
 361 $ sudo systemctl daemon-reload
 362 ```
 363
 364 Restart PeerTube and check the logs:
 365
 366 ```
 367 $ sudo systemctl restart peertube && sudo journalctl -fu peertube
 368 ```
 369
 370 ### Things went wrong?
 371
 372 Change `peertube-latest` destination to the previous version and restore your SQL backup:
 373
 374 ```
 375 $ OLD_VERSION="v0.42.42" && SQL_BACKUP_PATH="backup/sql-peertube_prod-2018-01-19T10:18+01:00.bak" && \
 376     cd /var/www/peertube && sudo -u peertube unlink ./peertube-latest && \
 377     sudo -u peertube ln -s "versions/peertube-$OLD_VERSION" peertube-latest && \
 378     sudo -u postgres pg_restore -c -C -d postgres "$SQL_BACKUP_PATH" && \
 379     sudo systemctl restart peertube
 380 ```