2019-03-28 16:46:30 +00:00
# Installing on Alpine Linux
2021-08-10 06:09:31 +00:00
2022-07-15 12:27:16 +00:00
{! installation/otp_vs_from_source_source.include !}
2021-08-10 06:09:31 +00:00
2019-03-28 16:46:30 +00:00
## Installation
2022-07-07 18:17:31 +00:00
This guide is a step-by-step installation guide for Alpine Linux. The instructions were verified against Alpine v3.16 standard image. You might miss additional dependencies if you use `netboot` instead.
2019-08-24 10:16:27 +00:00
2022-07-07 18:17:31 +00:00
As of Alpine Linux v3.16, `doas` is the preferred way of running privileged commands, which is what this guide will use.
If you are running an earlier version, replace `doas` with `sudo` (and use `sudo -Hu akkoma` instead of `doas -u akkoma` ).
If you want to run this guide with root, ignore the `doas` at the beginning of the lines, unless it calls a user like `doas -u akkoma` ; in this case, use `su -l <username> -s $SHELL -c 'command'` instead.
2019-03-28 16:46:30 +00:00
2022-07-15 12:27:16 +00:00
{! installation/generic_dependencies.include !}
2019-03-28 16:46:30 +00:00
### Prepare the system
2023-04-22 22:05:31 +00:00
* The community repository must be enabled in `/etc/apk/repositories` . Depending on which version and mirror you use, this looks like `https://dl-5.alpinelinux.org/alpine/v3.16/community` . If you autogenerated the mirror during installation:
2019-03-28 16:46:30 +00:00
```shell
2019-08-24 10:16:27 +00:00
awk 'NR==2' /etc/apk/repositories | sed 's/main/community/' | tee -a /etc/apk/repositories
2019-03-28 16:46:30 +00:00
```
* Then update the system, if not already done:
```shell
2022-07-07 18:17:31 +00:00
doas apk update
doas apk upgrade
2019-03-28 16:46:30 +00:00
```
* Install some tools, which are needed later:
```shell
2022-07-07 18:17:31 +00:00
doas apk add git build-base cmake file-dev
2019-03-28 16:46:30 +00:00
```
### Install Elixir and Erlang
* Install Erlang and Elixir:
```shell
2022-07-07 18:17:31 +00:00
doas apk add erlang elixir
2019-03-28 16:46:30 +00:00
```
2023-04-22 22:05:31 +00:00
* Install `erlang-eldap` if you want to enable LDAP authenticator
2022-07-27 21:48:13 +00:00
```shell
doas apk add erlang-eldap
```
2019-03-28 16:46:30 +00:00
### Install PostgreSQL
2023-04-22 22:05:31 +00:00
* Install PostgreSQL server:
2019-03-28 16:46:30 +00:00
```shell
2022-07-07 18:17:31 +00:00
doas apk add postgresql postgresql-contrib
2019-03-28 16:46:30 +00:00
```
* Initialize database:
```shell
2022-07-07 18:17:31 +00:00
doas rc-service postgresql start
2019-03-28 16:46:30 +00:00
```
2023-04-22 22:05:31 +00:00
* Enable and start PostgreSQL server:
2019-03-28 16:46:30 +00:00
```shell
2022-07-07 18:17:31 +00:00
doas rc-update add postgresql
2019-03-28 16:46:30 +00:00
```
2021-01-10 08:25:36 +00:00
### Install media / graphics packages (optional, see [`docs/installation/optional/media_graphics_packages.md`](../installation/optional/media_graphics_packages.md))
2020-09-26 16:32:16 +00:00
```shell
2022-07-07 18:17:31 +00:00
doas apk add ffmpeg imagemagick exiftool
2020-09-26 16:32:16 +00:00
```
2022-07-02 21:00:01 +00:00
### Install AkkomaBE
2019-03-28 16:46:30 +00:00
2022-07-02 21:00:01 +00:00
* Add a new system user for the Akkoma service:
2019-03-28 16:46:30 +00:00
```shell
2022-07-07 18:17:31 +00:00
doas addgroup akkoma
doas adduser -S -s /bin/false -h /opt/akkoma -H -G akkoma akkoma
2019-03-28 16:46:30 +00:00
```
2022-07-07 18:17:31 +00:00
**Note**: To execute a single command as the Akkoma system user, use `doas -u akkoma command` . You can also switch to a shell by using `doas -su akkoma` . If you don’ t have and want `doas` on your system, you can use `su` as root user (UID 0) for a single command by using `su -l akkoma -s $SHELL -c 'command'` and `su -l akkoma -s $SHELL` for starting a shell.
2019-03-28 16:46:30 +00:00
2022-12-16 16:23:31 +00:00
* Git clone the AkkomaBE repository from stable-branch and make the Akkoma user the owner of the directory:
2019-03-28 16:46:30 +00:00
```shell
2022-07-07 18:17:31 +00:00
doas mkdir -p /opt/akkoma
doas chown -R akkoma:akkoma /opt/akkoma
2022-12-16 16:23:31 +00:00
doas -u akkoma git clone https://akkoma.dev/AkkomaGang/akkoma.git -b stable /opt/akkoma
2019-03-28 16:46:30 +00:00
```
* Change to the new directory:
```shell
2022-07-02 21:00:01 +00:00
cd /opt/akkoma
2019-03-28 16:46:30 +00:00
```
2022-07-02 21:00:01 +00:00
* Install the dependencies for Akkoma and answer with `yes` if it asks you to install `Hex` :
2019-03-28 16:46:30 +00:00
```shell
2022-07-07 18:17:31 +00:00
doas -u akkoma mix deps.get
2019-03-28 16:46:30 +00:00
```
2022-07-07 18:17:31 +00:00
* Generate the configuration: `doas -u akkoma env MIX_ENV=prod mix pleroma.instance gen`
2019-03-28 16:46:30 +00:00
* Answer with `yes` if it asks you to install `rebar3` .
2023-04-22 22:05:31 +00:00
* This may take some time, because parts of Akkoma get compiled first.
* After that, it will ask you a few questions about your instance and generates a configuration file in `config/generated_config.exs` .
2019-03-28 16:46:30 +00:00
2022-12-16 16:23:31 +00:00
* Check the configuration and if all looks right, rename it, so Akkoma will load it (`prod.secret.exs` for productive instances):
2019-03-28 16:46:30 +00:00
```shell
2022-07-07 18:17:31 +00:00
doas -u akkoma mv config/{generated_config.exs,prod.secret.exs}
2019-03-28 16:46:30 +00:00
```
2023-04-22 22:05:31 +00:00
* The previous command also creates the file `config/setup_db.psql` , with which you can create the database:
2019-03-28 16:46:30 +00:00
```shell
2022-07-07 18:17:31 +00:00
doas -u postgres psql -f config/setup_db.psql
2019-03-28 16:46:30 +00:00
```
* Now run the database migration:
```shell
2022-07-07 18:17:31 +00:00
doas -u akkoma env MIX_ENV=prod mix ecto.migrate
2019-03-28 16:46:30 +00:00
```
2022-07-02 21:00:01 +00:00
* Now you can start Akkoma already
2019-03-28 16:46:30 +00:00
```shell
2022-07-07 18:17:31 +00:00
doas -u akkoma env MIX_ENV=prod mix phx.server
2019-03-28 16:46:30 +00:00
```
### Finalize installation
2023-04-22 22:05:31 +00:00
If you want to open your newly installed instance to the world, you should run NGINX or some other webserver/proxy in front of Akkoma and you should consider to create an OpenRC service file for Akkoma.
2019-03-28 16:46:30 +00:00
2023-04-22 22:05:31 +00:00
#### NGINX
2019-03-28 16:46:30 +00:00
2023-04-22 22:05:31 +00:00
* Install NGINX, if not already done:
2019-03-28 16:46:30 +00:00
```shell
2022-07-07 18:17:31 +00:00
doas apk add nginx
2019-03-28 16:46:30 +00:00
```
2023-04-22 22:05:31 +00:00
* Set up your SSL cert, using your method of choice or Certbot. If using Certbot, first install it:
2019-03-28 16:46:30 +00:00
```shell
2022-07-07 18:17:31 +00:00
doas apk add certbot
2019-03-28 16:46:30 +00:00
```
and then set it up:
```shell
2022-07-07 18:17:31 +00:00
doas mkdir -p /var/lib/letsencrypt/
doas certbot certonly --email < your @ emailaddress > -d < yourdomain > --standalone
2019-03-28 16:46:30 +00:00
```
2023-04-22 22:05:31 +00:00
If that doesn’ t work, make sure, that NGINX is not already running. If it still doesn’ t work, try setting up NGINX first (change SSL “on” to “off” and try again).
2019-03-28 16:46:30 +00:00
2023-04-22 22:05:31 +00:00
* Copy the example NGINX configuration to the NGINX folder
2019-03-28 16:46:30 +00:00
```shell
2022-07-07 18:17:31 +00:00
doas cp /opt/akkoma/installation/nginx/akkoma.nginx /etc/nginx/conf.d/akkoma.conf
2019-03-28 16:46:30 +00:00
```
2023-04-22 22:05:31 +00:00
* Before starting NGINX, edit the configuration and change it to your needs. You must change `server_name` and the paths to the certificates. You can use `nano` (install with `apk add nano` if missing).
2019-08-24 10:16:27 +00:00
```
server {
server_name your.domain;
listen 80;
...
}
server {
server_name your.domain;
listen 443 ssl http2;
...
ssl_trusted_certificate /etc/letsencrypt/live/your.domain/chain.pem;
ssl_certificate /etc/letsencrypt/live/your.domain/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/your.domain/privkey.pem;
...
}
```
2023-04-22 22:05:31 +00:00
* Enable and start NGINX:
2019-03-28 16:46:30 +00:00
```shell
2022-07-07 18:17:31 +00:00
doas rc-update add nginx
doas rc-service nginx start
2019-03-28 16:46:30 +00:00
```
2023-04-22 22:05:31 +00:00
If you need to renew the certificate in the future, uncomment the relevant location block in the NGINX config and run:
2019-03-28 16:46:30 +00:00
```shell
2022-07-07 18:17:31 +00:00
doas certbot certonly --email < your @ emailaddress > -d < yourdomain > --webroot -w /var/lib/letsencrypt/
2019-03-28 16:46:30 +00:00
```
#### OpenRC service
* Copy example service file:
```shell
2022-07-07 18:17:31 +00:00
doas cp /opt/akkoma/installation/init.d/akkoma /etc/init.d/akkoma
2019-03-28 16:46:30 +00:00
```
* Make sure to start it during the boot
```shell
2022-07-07 18:17:31 +00:00
doas rc-update add akkoma
2019-03-28 16:46:30 +00:00
```
#### Create your first user
If your instance is up and running, you can create your first user with administrative rights with the following task:
```shell
2022-07-07 18:17:31 +00:00
doas -u akkoma env MIX_ENV=prod mix pleroma.user new < username > < your @ emailaddress > --admin
2019-03-28 16:46:30 +00:00
```
2022-08-30 09:56:33 +00:00
{! installation/frontends.include !}
2019-03-28 16:46:30 +00:00
#### Further reading
2022-07-15 12:27:16 +00:00
{! installation/further_reading.include !}
2019-03-28 16:46:30 +00:00
2022-07-15 12:27:16 +00:00
{! support.include !}