mirror of
https://git.asonix.dog/asonix/pict-rs
synced 2024-12-22 11:21:24 +00:00
Add a guide for running pict-rs on ubuntu and debian
This commit is contained in:
parent
b8f9c00d30
commit
519c4c8af7
1 changed files with 229 additions and 0 deletions
229
docs/ubuntu-and-debian.md
Normal file
229
docs/ubuntu-and-debian.md
Normal file
|
|
@ -0,0 +1,229 @@
|
||||||
|
# pict-rs on Ubuntu and Debian
|
||||||
|
|
||||||
|
### The problem
|
||||||
|
|
||||||
|
At the time of writing, ImageMagick 7 has not been packaged for Debian Sid. This is a problem for
|
||||||
|
pict-rs, which depends on ImageMagick 7's commandline interface for media processing. Ubuntu users
|
||||||
|
are also affected, since Ubuntu inherits the Imagemagick package from Debian in the `universe`
|
||||||
|
archive.
|
||||||
|
|
||||||
|
pict-rs is also developed against ffmpeg 6, although from my testing it seems like the required
|
||||||
|
interfaces exist as far back as ffmpeg 4.4, which is the current stable version in Ubuntu 22.04. I
|
||||||
|
believe ffmpeg 5 is being prepped for the next Ubuntu release (23.10).
|
||||||
|
|
||||||
|
### Possible Solutions
|
||||||
|
|
||||||
|
Running pict-rs on an Ubuntu or Debian system can be done in the following ways:
|
||||||
|
1. Download the [ImageMagick AppImage](https://imagemagick.org/script/download.php). This is option
|
||||||
|
only works for running pict-rs on x86_64
|
||||||
|
2. Compile ImageMagick 7 from source. User MichelSup in the [pict-rs matrix
|
||||||
|
channel]https://matrix.to/#/%23pictrs:matrix.asonix.dog?via=matrix.asonix.dog() has done this.
|
||||||
|
3. Run pict-rs with `Nix`
|
||||||
|
|
||||||
|
Since I do my development for pict-rs on NixOS, I will document running pict-rs with Nix here.
|
||||||
|
|
||||||
|
### Installing with Nix
|
||||||
|
|
||||||
|
#### Install Nix
|
||||||
|
|
||||||
|
The official instructions [live here](https://nixos.org/download.html), but on Ubuntu you can follow
|
||||||
|
these steps:
|
||||||
|
```bash
|
||||||
|
$ sudo apt update
|
||||||
|
$ sudo apt install curl xz-utils
|
||||||
|
$ sh <(curl -L https://nixos.org/nix/install) --daemon
|
||||||
|
```
|
||||||
|
|
||||||
|
The Nix installer will ask if it's okay for it to make the changes it wants to make, and it will
|
||||||
|
print detailed logs about what it's doing.
|
||||||
|
|
||||||
|
After you get nix installed, we need to enable some nix features.
|
||||||
|
|
||||||
|
Open up `/etc/nix/nix.conf` in your favorite text editor (vim) and add the following line:
|
||||||
|
```
|
||||||
|
experimental-features = nix-command flakes
|
||||||
|
```
|
||||||
|
|
||||||
|
#### Build pict-rs
|
||||||
|
|
||||||
|
Now that nix is installed and configured, we can download and build the pict-rs nix package.
|
||||||
|
|
||||||
|
We'll fetch the latest code in the v0.4.x branch with git. This branch holds the latest changes
|
||||||
|
intended for releases in the 0.4 cycle.
|
||||||
|
```bash
|
||||||
|
$ sudo apt install git
|
||||||
|
$ git clone -b v0.4.x https://git.asonix.dog/asonix/pict-rs
|
||||||
|
```
|
||||||
|
|
||||||
|
And then we'll build the pict-rs nix package.
|
||||||
|
```bash
|
||||||
|
$ cd pict-rs
|
||||||
|
$ nix build
|
||||||
|
```
|
||||||
|
|
||||||
|
This will create a nix package with pict-rs and it's dependencies (exiftool, ffmpeg, and
|
||||||
|
imagemagick). You can see the contents of the package in the `result` symlink that was created by
|
||||||
|
the `nix build` command.
|
||||||
|
|
||||||
|
```bash
|
||||||
|
$ ls -lh | grep result
|
||||||
|
lrwxrwxrwx 1 asonix asonix 57 jul 9 19:47 result -> /nix/store/lblq0ns1p86qnpm3kd86ljpg2yx2i06b-pict-rs-0.4.1
|
||||||
|
|
||||||
|
$ ls result
|
||||||
|
bin
|
||||||
|
|
||||||
|
$ ls result/bin
|
||||||
|
pict-rs
|
||||||
|
```
|
||||||
|
|
||||||
|
> As an aside, this `pict-rs` file in `result/bin` is actually a shell script and not the binary.
|
||||||
|
This script's purpose is to bring pict-rs' dependencies into the `$PATH` variable before
|
||||||
|
invoking the real pict-rs binary. This is part of how Nix keeps applications isolated from each
|
||||||
|
other while still allowing inter-package dependencies to exist.
|
||||||
|
|
||||||
|
#### Configuring systemd
|
||||||
|
|
||||||
|
Depending on when you follow these instructions, the produced pict-rs binary may have a different
|
||||||
|
path in the nix store. This is expected.
|
||||||
|
|
||||||
|
Now that we have a binary, we can configure it to start with `systemd`. This means writing a unit
|
||||||
|
file that will start the pict-rs binary when the machine boots. We have a couple options for this,
|
||||||
|
so I'll talk about both here.
|
||||||
|
|
||||||
|
Before we do any of that, let's go ahead and write the start of our unit file. Open a new file
|
||||||
|
called `pict-rs.service`
|
||||||
|
```service
|
||||||
|
[Unit]
|
||||||
|
Description=A simple image host
|
||||||
|
Documentation=https://git.asonix.dog/asonix/pict-rs
|
||||||
|
After=network-online.target
|
||||||
|
```
|
||||||
|
|
||||||
|
This just sets up some metadata and tells the operating system to wait until the network has been
|
||||||
|
brought up before starting pict-rs.
|
||||||
|
|
||||||
|
After the `[Unit]` section, we'll add a new section called `[Service]`. This describes how to launch
|
||||||
|
pict-rs, and when to restart it if needed. We'll need that symlink path from earlier for this step,
|
||||||
|
too.
|
||||||
|
|
||||||
|
```service
|
||||||
|
[Service]
|
||||||
|
Type=simple
|
||||||
|
ExecStart=/nix/store/lblq0ns1p86qnpm3kd86ljpg2yx2i06b-pict-rs-0.4.1 run
|
||||||
|
Restart=on-failure
|
||||||
|
```
|
||||||
|
|
||||||
|
These are the minimum required fields to launch pict-rs, but it probably won't run how you'd like.
|
||||||
|
We'll configure pict-rs next
|
||||||
|
|
||||||
|
##### Adding configuration to the Unit File
|
||||||
|
|
||||||
|
This is the easier route, and will keep all the configuration in one file. In the same service file,
|
||||||
|
in the same `[Service]` section, we'll set some environment variables.
|
||||||
|
|
||||||
|
```service
|
||||||
|
Environment="PICTRS__SERVER__ADDRESS=127.0.0.1:8080"
|
||||||
|
Environment="PICTRS__SERVER__API_KEY=SOME-REALLY-SECRET-KEY"
|
||||||
|
Environment="PICTRS__TRACING__LOGGING__TARGETS=warn"
|
||||||
|
Environment="PICTRS__MEDIA__FORMAT=avif"
|
||||||
|
Environment="PICTRS__REPO__PATH=/var/lib/pict-rs/sled"
|
||||||
|
Environment="PICTRS__REPO__EXPORT_PATH=/var/lib/pict-rs/sled"
|
||||||
|
Environment="PICTRS__STORE__PATH=/var/lib/pict-rs/files"
|
||||||
|
```
|
||||||
|
|
||||||
|
This tells pict-rs to run just on the local box on part 8080, sets an api key for access to the
|
||||||
|
internel endpoints, reduces the log output to just warnings and errors, tells pict-rs to
|
||||||
|
automatically convert uploaded images to avif, and sets the directories for pict-rs' state to
|
||||||
|
`/var/lib/pict-rs`.
|
||||||
|
|
||||||
|
In all, our unit file should look like this:
|
||||||
|
```service
|
||||||
|
[Unit]
|
||||||
|
Description=A simple image host
|
||||||
|
Documentation=https://git.asonix.dog/asonix/pict-rs
|
||||||
|
After=network-online.target
|
||||||
|
|
||||||
|
[Service]
|
||||||
|
Type=simple
|
||||||
|
ExecStart=/nix/store/lblq0ns1p86qnpm3kd86ljpg2yx2i06b-pict-rs-0.4.1 run
|
||||||
|
Restart=on-failure
|
||||||
|
Environment="PICTRS__SERVER__ADDRESS=127.0.0.1:8080"
|
||||||
|
Environment="PICTRS__SERVER__API_KEY=SOME-REALLY-SECRET-KEY"
|
||||||
|
Environment="PICTRS__TRACING__LOGGING__TARGETS=warn"
|
||||||
|
Environment="PICTRS__MEDIA__FORMAT=avif"
|
||||||
|
Environment="PICTRS__REPO__PATH=/var/lib/pict-rs/sled-repo"
|
||||||
|
Environment="PICTRS__REPO__EXPORT_PATH=/var/lib/pict-rs/exports"
|
||||||
|
Environment="PICTRS__STORE__PATH=/var/lib/pict-rs/files"
|
||||||
|
```
|
||||||
|
|
||||||
|
Once the unit file is ready, save it to `/etc/systemd/system/pict-rs.service`.
|
||||||
|
|
||||||
|
|
||||||
|
##### Adding a dedicated pict-rs configuration file
|
||||||
|
|
||||||
|
Instead of configuring pict-rs with environment variables, we can instead use a configuration file.
|
||||||
|
First, we'll update our `ExecStart` entry to tell pict-rs to load the configuration file.
|
||||||
|
|
||||||
|
```service
|
||||||
|
ExecStart=/nix/store/lblq0ns1p86qnpm3kd86ljpg2yx2i06b-pict-rs-0.4.1 -c /etc/pict-rs.toml run
|
||||||
|
```
|
||||||
|
|
||||||
|
Our full service file should now look like this:
|
||||||
|
```service
|
||||||
|
[Unit]
|
||||||
|
Description=A simple image host
|
||||||
|
Documentation=https://git.asonix.dog/asonix/pict-rs
|
||||||
|
After=network-online.target
|
||||||
|
|
||||||
|
[Service]
|
||||||
|
Type=simple
|
||||||
|
ExecStart=/nix/store/lblq0ns1p86qnpm3kd86ljpg2yx2i06b-pict-rs-0.4.1 -c /etc/pict-rs.toml run
|
||||||
|
Restart=on-failure
|
||||||
|
```
|
||||||
|
|
||||||
|
Save this service file to `/etc/systemd/system/pict-rs.service`
|
||||||
|
|
||||||
|
Now, we'll configure pict-rs with toml. Open a new file at `/etc/pict-rs.toml`
|
||||||
|
|
||||||
|
We'll add the following configuration:
|
||||||
|
```toml
|
||||||
|
[server]
|
||||||
|
address = "127.0.0.1:8080"
|
||||||
|
api_key = "SOME-REALLY-SECRET-KEY"
|
||||||
|
|
||||||
|
[tracing.logging]
|
||||||
|
targets = "warn"
|
||||||
|
|
||||||
|
[media]
|
||||||
|
format = "avif"
|
||||||
|
|
||||||
|
[repo]
|
||||||
|
path = "/var/lib/pict-rs/sled-repo"
|
||||||
|
export_path = "/var/lib/pict-rs/exports"
|
||||||
|
|
||||||
|
[store]
|
||||||
|
path = "/var/lib/pict-rs/files"
|
||||||
|
```
|
||||||
|
|
||||||
|
After saving that configuration file, we're ready to start pict-rs.
|
||||||
|
|
||||||
|
|
||||||
|
#### Starting pict-rs
|
||||||
|
|
||||||
|
Now that we have created a unit file for pict-rs, we are able to start the service. You can do this
|
||||||
|
with the following commands:
|
||||||
|
```bash
|
||||||
|
$ sudo systemctl daemon-reload
|
||||||
|
$ sudo systemctl enable --now pict-rs
|
||||||
|
```
|
||||||
|
|
||||||
|
If everything went well, `pict-rs` should now be running on your system. You can follow its logs
|
||||||
|
with this command:
|
||||||
|
```bash
|
||||||
|
$ journalctl -xfu pict-rs
|
||||||
|
```
|
||||||
|
|
||||||
|
I hope this has been helpful to Ubuntu and Debian server admins. If you are familiar with packaging
|
||||||
|
software for Debian, consider stepping up to help maintain the ImageMagick package. There was a call
|
||||||
|
for help maintaining it last year on the [debian bug
|
||||||
|
tracker](https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=1017366)
|
||||||
Loading…
Reference in a new issue