Alpine Linux - User contributions [en]

Mako

2025-06-04T20:11:06Z

Faust: /* Configuration */

{{DISPLAYTITLE:mako}}
[https://github.com/emersion/mako mako] is a lightweight notification daemon for [[Wayland]].

== Prerequisites ==

* Mako requires [[D-Bus]] service.

== Installation ==

Install the {{pkg|mako}} package as per command: {{cmd|# apk add mako}}

== Configuration ==

To configure mako as [[OpenRC#User services|User service in OpenRC]], an executable file {{Path|~/.config/rc/init.d/mako}} has to be created with the following content {{Cat|~/.config/rc/init.d/mako|<nowiki>#!/sbin/openrc-run

description="org.freedesktop.Notifications"

command="/usr/bin/mako"

supervisor=supervise-daemon
error_logger="logger -t '${RC_SVCNAME}' -p daemon.error"

depends() {
use dbus
}</nowiki>}}

Follow the steps outlined in [[OpenRC#User services|User service in OpenRC]], if not already done. Finally, add the service for mako as follows: {{Cmd|$ rc-update add --user mako gui}}

The working of mako service can be tested by issuing the command {{ic|$ notify-send "Test for mako User service"}}. Install the {{pkg|libnotify}} package, if the command {{ic|notify-send}} is not available.

== Troubleshooting ==

=== org.freedesktop.DBus.Error.NoReply ===

{{ic|GDBus.Error:org.freedesktop.DBus.Error.NoReply: Message recipient disconnected from message bus without replying}}

To resolve the above error, if you are using <code>dbus-run-session</code> wrapper to launch sway, set D-Bus variables by adding the following line to sway [[Sway#Sway config file|config]] file:
exec dbus-update-activation-environment WAYLAND_DISPLAY XDG_CURRENT_DESKTOP=sway

=== Failed to acquire service name ===

<Pre>daemon.err mako: Failed to acquire service name: File exists
daemon.err mako: Is a notification daemon already running?</Pre>
{{Todo|The above message appears in {{Path|/var/log/messages}} randomly, but no cause is found yet. Please update here, if reason and resolution is found. Earlier attempts at naming the mako service executable file as {{ic|org.freedesktop.Notifications}} did not make any difference.}}

== See also ==
* [https://github.com/emersion/mako/wiki mako wiki]

[[Category:System Administration]]

Mako

2025-06-04T20:10:50Z

Faust: /* Configuration */

{{DISPLAYTITLE:mako}}
[https://github.com/emersion/mako mako] is a lightweight notification daemon for [[Wayland]].

== Prerequisites ==

* Mako requires [[D-Bus]] service.

== Installation ==

Install the {{pkg|mako}} package as per command: {{cmd|# apk add mako}}

== Configuration ==

To configure mako as [[OpenRC#User services|User service in OpenRC]], an executable file {{Path|~.config/rc/init.d/mako}} has to be created with the following content {{Cat|~/.config/rc/init.d/mako|<nowiki>#!/sbin/openrc-run

description="org.freedesktop.Notifications"

command="/usr/bin/mako"

supervisor=supervise-daemon
error_logger="logger -t '${RC_SVCNAME}' -p daemon.error"

depends() {
use dbus
}</nowiki>}}

Follow the steps outlined in [[OpenRC#User services|User service in OpenRC]], if not already done. Finally, add the service for mako as follows: {{Cmd|$ rc-update add --user mako gui}}

The working of mako service can be tested by issuing the command {{ic|$ notify-send "Test for mako User service"}}. Install the {{pkg|libnotify}} package, if the command {{ic|notify-send}} is not available.

== Troubleshooting ==

=== org.freedesktop.DBus.Error.NoReply ===

{{ic|GDBus.Error:org.freedesktop.DBus.Error.NoReply: Message recipient disconnected from message bus without replying}}

To resolve the above error, if you are using <code>dbus-run-session</code> wrapper to launch sway, set D-Bus variables by adding the following line to sway [[Sway#Sway config file|config]] file:
exec dbus-update-activation-environment WAYLAND_DISPLAY XDG_CURRENT_DESKTOP=sway

=== Failed to acquire service name ===

<Pre>daemon.err mako: Failed to acquire service name: File exists
daemon.err mako: Is a notification daemon already running?</Pre>
{{Todo|The above message appears in {{Path|/var/log/messages}} randomly, but no cause is found yet. Please update here, if reason and resolution is found. Earlier attempts at naming the mako service executable file as {{ic|org.freedesktop.Notifications}} did not make any difference.}}

== See also ==
* [https://github.com/emersion/mako/wiki mako wiki]

[[Category:System Administration]]

MySQL

2025-03-11T22:05:20Z

Faust: rephrase and update GH stars

MySQL is the most popular relational database server in free software for two simple reasons (which are not the best technical reasons):
# It's simple and very easy to use
# It is very similar to SQLSERVER and is also used in other systems

'''In the world of Linux Alpine there is a software that provides it''', it is [[MariaDB]], here we have a brief of info about compatibility and differences, but in short there's no great differences, if you have doubts check [[MySQL#MariaDB vs MySQL|MariaDB vs MySQL section here]]

'''In the wiki there are two approaches for its use''', the professional one (for servers and deploys) and the [[MariaDB|fast and simple]] usage (for developers and/or enthusiasts):

= MariaDB - fast and simple use =

{{:MariaDB}}

= MySQL (MariaDB) - Production usage =

[https://mariadb.org/ MariaDB] is a community-developed fork of the MySQL relational database management system intended to remain free under the GNU GPL. It is notable for being led by the original developers of MySQL, who forked it due to concerns over its acquisition by Oracle.

This page assumed that you have a general knowledge about MariaDB, so if you are new to MySQL first take a look at the [[MariaDB|MariaDB wiki page]] for information about how are packaged for alpine linux.

== Installation ==

Alpine Linux has dummy counterparts packages for those that are not close to that change from ''mysql'' to ''mariadb'' naming packages, please check the [[MariaDB|MariaDB wiki page]] for more information.

Take in consideration that the user <code>mysql</code> was created during instalation of packages, in the initialization section two users will be created in database init: <code>root</code> and <code>mysql</code>, and in that point only if are in their respective system accounts, will be able to connect to the database service.

<pre><nowiki>
apk add mysql mysql-client
</nowiki></pre>

That will install the most used ones.. <code>mariadb-cient</code> and <code>mariadb-server</code>, rest of packages are brief described here for more information, here are listed in orden of relevance for production server

{| class="wikitable"
|-
! MySQL name package !! Since Alpine: !! Brief usage !! Related package
|-
| mysql || v2 || it's a dummy package to easy install of mariadb || mariadb
|-
| mysql-client || v2 || it's a dummy package to easy install of commands tools || mariadb-client
|-
| mariadb || v2 || server equivalent to mysql-server || mariadb-common
|-
| mariadb-client || v2 || connection command line and tools || mariadb-common
|-
| mariadb-doc || v3.0 || manpages are there! || man man-pages
|-
| mariadb-connector-odbc || edge || coding or making OS level connections, to any DB without libs install || .
|-
| mariadb-connector-c || v3.8 || coding connection on C sources || mariadb-connector-c-dev
|-
| mariadb-backup || v3.8 || to external backup devices, not widely used, in past was inside mariadb package || .
|-
| mariadb-server-utils || v3.8 || server commands not widely used, in past was inside mariadb package || .
|-
| mariadb-dev || v3.1 || Need for compilations depends on source code || .
|-
| mariadb-test || v3.3 || testing suite from MariaDB tools || .
|-
| mariadb-mytop || v3.9 || data performance monitoring || .
|-
| mariadb-plugin-rocksdb || v3.9 || plain key-value event relational for data || .
|-
| mariadb-static || v3.8 || static libs for static non depends linking in builds || .
|-
| mariadb-embedded || v3.9 || the libmysqld identical interface as the C client || mariadb-embedded-dev
|-
| mariadb-embedded-dev || v3.9 || use the normal mysql.h and link with libmysqld instead of libmysqlclient || mariadb-dev
|-
| mariadb-openrc || v3.8 || separate scripts, in past was embebed on server package || .
|}

== Initialization ==

The alpine package of MySQL/MariaDB are like normal tarball of MySQL one, admins must be know what they want.. there's no automatic window-like here.

The ''datadir'' are located to <code>/var/lib/mysql</code> must be owned by the mysql user and group. You can modify this behavior but must edit the service file at <code>/etc/init.d</code> directory. Also, you need to set <code><nowiki>datadir=<YOUR_DATADIR></nowiki></code> under section <code>[mysqld]</code> at the config file.

# Initialize the main mysql database, and the data dir as standardized to <code>/var/lib/mysql</code> by the rc script
# Then initialize the service, root account and socket connection are enabled without password at this point
# Setup the root account by asignes a proper password, this are purely paranoid. due next step already do that!
# Setup and init the installation by running the <code>mysql_secure_installation</code>
# Setup permissions for manage others users and databases

<pre>
<nowiki>
mysql_install_db --user=mysql --datadir=/var/lib/mysql

rc-service mariadb start

mysqladmin -u root password toor
</nowiki>
</pre>

After that, all are initializated to proceed with configuration, now can be done using the <code>
mysql_secure_installation</code> script at the next section:

== Configuration ==

In order to finish setup into '''MariaDB''' now provide '''this script called <code>mysql_secure_instalation</code> that also are present as <code>mariadb-secure-installation</code>''', too. This script provides minimal and security setup to the database, and here are the questions made explained:

# '''Enter current password for root (enter for none):''' this are if you previously setup as we done in previous section a root password, just provide it and press enter, '''must be provided due we already set previously''' and from now, this sript will access to the engine and alter many setting on the database. Correct respond are <code>OK, successfully used password, moving on...</code>
# '''Switch to unix_socket authentication [Y/n]''' Setting the root password or using the unix_socket ensures that only admins can log into engine database. Since mysql 5.6 and mariadb 10.2 a new auth mechanish are set, by socket authentiaction, when system user are same as mysql/mariadb user, in this case, no password are need. In production servers this are not the case and must be disabled, '''so answer NO''', and response will be <code>... skipping.</code>
# '''Change the root password? [Y/n]''' this answer are here only if the first one are just enter, or if can provide a better passowrd if no unix socket are set. Just press "n" only if you provided a good password, otherwise just
# '''Remove anonymous users? [Y/n]''' this permits remove the anonymous user created to log using socket authentication, only working on unix-like system. In any case, '''production system must remove it, so answer Y''' and proper respond must be <code>... Success!</code>.
# '''Disallow root login remotely? [Y/n]''' Normally, root should only be allowed to connect from 'localhost'. This ensures that someone cannot guess at the root password from the network. For sure answer Y''' and proper respond must be <code>... Success!</code>.
# '''Remove test database and access to it? [Y/n]''' By default, MariaDB comes with a database named 'test' that anyone can access. This is also intended only for testing, and should be removed, so answer Y''' and proper respond must be <code>... Success!</code>.
# '''Reload privilege tables now? [Y/n]''' Reloading the privilege tables will ensure that all changes made so far will take effect immediately, so answer Y''' and proper respond must be <code>... Success!</code>.

After reponse all the questions.. restart the service with <code>rc-service mariadb restart</code>

=== Configuration files ===

Due today were influenced by systemd standardization, the famous <nowiki>my.cnf</nowiki> are not more the main config file for the server engine. Now only few variables are defined there and all the settings are provided by independent files into the <code>/etc/my.cnf.d/</code> directory, user own config files are under <code>~/.my.cnf</code> config file of each home dir, and are read after global ones; so then we have:

{| class="wikitable"
|-
! Config file !! Path and name !! Versions of Alpine !! Contents to configure
|-
| my.cnf || <nowiki>/etc/mysql/my.cnf</nowiki> || v2 to v3.8 || All the directives, Global config file
|-
| mariadb-server.cnf || /etc/my.cnf.d/mariadb-server.cnf || since 3.9 || First Global config file, main directives
|-
| .my.cnf || <nowiki>$HOME</nowiki> || all || user name only config directives
|}

=== Production settings ===

These setting are only recommended for some server settings, there are the recommendation for high production settings:

{| class="wikitable"
|-
! Config setting !! Default !! Recommended !! Explanation
|-
| main ram || 2G || 8G - 16G || MariaDB/MySQL can run with 512M or 1G of ram, high production must use minimun of 4G or more.
|-
| data dir disk type || any || SSD || MariaDB/MySQL must run with faster SSD if high request will be produced.
|-
| collation_server || utf8_unicode_ci || utf8mb4_unicode_ci || With 8mb4 some characters are able to use more than a single byte.
|-
| character_set_client || iso8859-1 || utf8 or utf8mb4 || Important due are standard, for left to right use 8mb4 flavor
|-
| max_connections || 151 || 100 || total_connections = total_processes * (total_threads + script_servers + 1)
|-
| max_heap_table_size || 16M || 32M || allocate more memory to memory tables, for memory storage engines
|-
| tmp_table_size || 16M || 32M || It allows the sub queries to remain more in memory, making them faster
|-
| join_buffer_size || 32M || 64M || It allows the join queries to remain more in memory rather in temp files
|-
| innodb_file_format || unset || Barracuda || will allow longer indexes for important most used tables
|-
| innodb_large_prefix || unset || 1 || Must set if Barracuda file format are choosen
|-
| innodb_buffer_pool_size || 128M || 456M || hold as much tables and indexes in system memory as is possible
|-
| innodb_read_io_threads || 16 || 32 || On high I/O systems, a value greater than 1 may allow the disk I/O to be more sequential
|-
| innodb_write_io_threads || 16 || 32 || Only if you have SSD storage for the data MySQL/MariaDB database and temp files
|-
| innodb_buffer_pool_instances || 1 || 2 or 4 || Only for older MySQL/MariaDB engines,
|-
| innodb_io_capacity || 200 || 1200 - 2600 || Only if you have SSD storage for the data MySQL/MariaDB database and temp files
|-
| innodb_io_capacity_max || 200 || 2400 - 5200 || Only if you have SSD storage for the data MySQL/MariaDB database and temp files
|}

If you have SSD disks, use the recommended suggestion, otherwise, use minimum suggested. If you have physical hard drives, use 2000 * the number of active drives in the array. If using NVMe or PCIe Flash, much larger numbers as high as 200000 can be used, but those lasted storage devices will be a short life of course.

Newer system Alpine packages can set in independent files in any case those commands always works and where are not apply just will ignore the output:

* On older Alpine system must set config files for MAX ALLOWED PACKETS to minimun proper amount:

<pre>
<nowiki>
sed -i "s|.*max_allowed_packet\s*=.*|max_allowed_packet = 100M|g" /etc/mysql/my.cnf
sed -i "s|.*max_allowed_packet\s*=.*|max_allowed_packet = 100M|g" /etc/my.cnf.d/mariadb-server.cnf
</nowiki>
</pre>

* Only allow local connections on cases where there's only one server or no expected to connect from others:

<pre>
<nowiki>
sed -i "s|.*bind-address\s*=.*|bind-address=127.0.0.1|g" /etc/mysql/my.cnf
sed -i "s|.*bind-address\s*=.*|bind-address=127.0.0.1|g" /etc/my.cnf.d/mariadb-server.cnf
</nowiki>
</pre>

* If are not in domain controller, dont search for hostnames to improve performance responses (ideal for local only servers):

<pre>
<nowiki>
sed -i "s|.*skip-networking.*|skip-networking|g" /etc/mysql/my.cnf
sed -i "s|.*skip-networking.*|skip-networking|g" /etc/my.cnf.d/mariadb-server.cnf
</nowiki>
</pre>

* Set default charset to UTF8MB4, in newer versions (since Alpine v3.9), just added a new file to added thus customization, but older versions (below Alpine v3.8)of the package does not have a charset section, so you must added manually to the main configuration in each respective section:

<pre>
<nowiki>
cat > /etc/my.cnf.d/mariadb-server-default-charset.cnf << EOF
[client]
default-character-set = utf8mb4

[mysqld]
collation_server = utf8mb4_unicode_ci
character_set_server = utf8mb4

[mysql]
default-character-set = utf8mb4
EOF
</nowiki>
</pre>

== Updating or comming from upgrading ==

Mayor Upgrades beetween Alpine linux version are so easy as change the repository version, but the MySQL/MariaDB engine need some extra steps when this are performed:

Upgrade databases on major releases
Upon a major version release of mariadb (for example mariadb-10.1.10-1 to mariadb-10.1.18-1), it is wise to upgrade databases:

# keep the old database (mysql sheme) structure of the engine daemon, currently this are not more the case, today this not make sense anymore
# upgrade the MariaDB/MySQL packages, of course with must be done if the upgrade process to mayor alpine version does not!
# run the <code>mysql_upgrade -u root -p</code> script, providing the password or root, (from the new package version) against the old still-running database (mysql sheme). This will produce some error messages; however, the upgrade will succeed.
# Restart the service

If are unable to run ''mysql_upgrade'' because MySQL cannot start try run MySQL in safemode with <code>mysqld_safe --datadir=/var/lib/mysql/</code> command and then run the <code>mysql_upgrade -u root -p</code> script.

= Relevant important notes =

== File system notes about the databases managed ==

'''Btrfs Notes'''

If the database (in <code>/var/lib/mysql</code>) resides on a [[Btrfs|btrfs]] file system, you should consider disabling '''Copy-on-Write''' for the directory before creating any database (schemes), after initialization you can enabled again. But .. on every database creation (scheme creation), you must disabled again, to avoid corrupted data.

'''ZFS Bock sizes'''

ZFS, unlike most other file systems, has a variable record size, or what is commonly referred to as a block size. By default, the recordsize on ZFS is 128KiB, which means it will dynamically allocate blocks of any size from 512B to 128KiB depending on the size of file being written. Most RDBMSes work in 8KiB-sized blocks by default. Although the block size is tunable for MySQL/MariaDB use an 8KiB block size by default.

It is usually desirable to tune ZFS instead to accommodate the databases, using a command such as <code>zfs set recordsize=8K /var/lib/mysql</code> (or change /var/lib/mysql to the mount point where /var/lib/mysql resides) and in the interest of saving memory, it is best to simply disable ZFS's caching of the database's file data and let the database do its own job with <code>zfs set primarycache=metadata /var/lib/mysql</code> (or change /var/lib/mysql to the mount point where /var/lib/mysql resides).

But beware, these kinds of tuning parameters are only if RDBMSes are setup in dedicated partitions, if your root and of course database are all in one partition, dont do that. Separate ones.

== Restore root password ==

<pre>
<nowiki>
rc-service mysql stop

kill `cat /run/mysqld/mysqld.pid`

/usr/bin/mysqld --datadir=/var/lib/mysql --pid-file=/run/mysqld/mysqld.pid --skip-grant-tables --skip-networking &

mysql -e "ALTER USER 'root'@'localhost' IDENTIFIED BY 'MyNewPass';FLUSH PRIVILEGES;ALTER USER 'root'@'localhost' IDENTIFIED BY 'MyNewPass';FLUSH PRIVILEGES;set password = password('MyNewPass');"

kill `cat /run/mysqld/mysqld.pid`

rc-service mariadb restart
</nowiki>
</pre>

= See Also =

* [[MariaDB|MariaDB wiki page]]
* [[Production LAMP system: Lighttpd + PHP + MySQL]]

[[Category:Newbie]]
[[Category:Server]]
[[Category:Database]]
[[Category:Development]]
[[Category:Security]]
[[Category:Production]]

= MariaDB vs MySQL =

It is more a matter of compatibility than of performance and characteristics (with the arrival of MySQL v8) .. and it depends on whether there is a purely business and support approach "zero concern".

MySQL, being from Oracle, establishes limits if a license is not purchased, MariaDB has a large connection pool, more than 200,000 connections, while MySQL has a smaller connection pool if it is not licensed.

However, MariaDB does not support data masking and dynamic column while MySQL supports it, also MariaDB although it has 12 new storage engines while MySQL has less these are very new and MySQL's are widely known and tested.

In terms of performance, MariaDB is only a little faster than MySQL, this is because MySQL implements more business features, but this is only noticeable using these many features.

Which is more optimal this is not clear .. in general MySQL should be less, and MariaDB faster, there is a third option which is Percona which is the same MySQL service but with special aggressive optimization patches for servers. Percona mysql code must be compiled in Alpine linux.

== Comparison table ==

{| class="wikitable"
|-
! Characteristic !! MariaDB !! MySQL
|-
| Storage Engines || up to 12 but many in development stage || less but well tested
|-
| Performance || just a little faster || less, there is almost no difference
|-
| Initial version || 2009 (5.3) || 1995 (3.0)
|-
| Data masking || no || yes
|-
| dynamic columns || no || yes
|-
| Monitoring || SQLyog || MySQLworkbench
|-
| Routing || MariaDB MaxScale || Mysql Router
|-
| Analytics || MariaDB ColumnStore || not have
|-
| Git starred times (github)|| [https://github.com/MariaDB/server around 5.9k] || [https://github.com/mysql/mysql-server around 11.2k]
|}

For more info check a review here: http://qgqlochekone.blogspot.com/2020/04/mariadb-mysql-and-mysqlworkbench.html

[[Category:Newbie]]
[[Category:Server]]
[[Category:Database]]
[[Category:Development]]

Include:Setup your system and account for building packages

2023-09-29T11:08:24Z

Faust: Explain how to share abuild signing keys between computers.

The {{Pkg|alpine-sdk}} is a metapackage that pulls in the most essential packages used to build new packages. Also install and configure a way to elevate privileges, such as sudo or doas, and an editor, such as vi, nano, micro.

{{Cmd|# apk add alpine-sdk}}

This would be a good time to [[Setting_up_a_new_user|create a normal user account for you to work in]]. To make life easier later, it's a good idea to add this user to the wheel group; operations that require superuser privileges can now be done with sudo or doas.

The [[Aports_tree|aports tree]] is in git so before we clone it, let's configure git.

{{Cmd|$ git config --global user.name "Your Full Name"
$ git config --global user.email "your@email.address"}}

Read carefully [[Development using git]] to grasp basic Git operations and how to configure for sending email patches.

Now we can clone the [[Aports_tree|aports tree]].

{{Cmd|$ git clone https://gitlab.alpinelinux.org/alpine/aports}}

Before we start creating or modifying [[APKBUILD_Reference|APKBUILD]] files, we need to setup abuild for our system and user. Edit the file {{Path|/etc/abuild.conf}} to your requirements.

Most of the defaults can be left alone, unless you are developing for a custom platform, in which case the comments in the file should guide you. The one field to edit is PACKAGER, so that you can get credit (or blame) for packages you create.

To use 'abuild -r' command to install dependency packages automatically.
{{Cmd|# addgroup <yourusername> abuild}}

We also need to prepare the location where the build process caches files when they are downloaded. By default this is {{Path|/var/cache/distfiles/}}. To create this directory and ensure that it is writeable, enter the following commands:

{{Cmd|# mkdir -p /var/cache/distfiles}}
{{Cmd|# chmod a+w /var/cache/distfiles}}

As an alternative to the second command, you can add yourself to the abuild group:

{{Cmd|# chgrp abuild /var/cache/distfiles}}
{{Cmd|# chmod g+w /var/cache/distfiles}}

{{Note|Remember to logout and login again for the group change to have effect.}}

The last step is to configure the security keys with the [[Abuild-keygen|abuild-keygen]] script for [[Abuild|abuild]] with the command:

{{Cmd|# abuild-keygen -a -i}}

If you want to share the generated keys between multiple computers ({{Path|~/.abuild}}), you will have to manually copy the generated public key into {{Path|/etc/apk/keys}} for the signing process of generated packages to work, example:

{{Cmd|# cp /home/user/.abuild/user@domain.tld-12345abc.rsa.pub /etc/apk/keys}}

[[Category:Development]]

Flatpak

2023-09-22T08:54:46Z

Faust: /* Troubleshooting */ add documentation for sandbox override

{{Draft|More documentation and testing is needed, but everything currently here should be safe to follow.}}

Flatpak is a technology for building and distributing applications with the goal of having a universal package format for all Linux distributons, it is similar to [https://en.wikipedia.org/wiki/Snap_(software) Snap],

== Setup / Installation ==

=== Runtime dependencies ===

* {{Pkg|dbus}}
* {{Pkg|xdg-desktop-portal}}
* an implementation of <code>xdg-desktop-portal</code>, e.g. {{Pkg|xdg-desktop-portal-gtk}}

{{Note|If you are running a window manager from {{Path|.xinitrc}}, make sure you are running a <code>dbus</code> session explicitly, i.e.:

{{Cmd|# exec dbus-launch --exit-with-session your_favourite_wm}}}}

=== Installing Flatpak Itself ===

''From: https://flatpak.org/setup/Alpine/''

{{Note|To install Flatpak you will need to enable the Community repository, See: [[Repositories#Managing_repositories|Repositories - Managing repositories]]}}

To install Flatpak run:

{{cmd|# apk add {{Pkg|flatpak}}}}

Next you need to add a repository, for this guide we will use the recommended repository, [https://flathub.org Flathub].

{{cmd|$ flatpak remote-add --user --if-not-exists flathub https://flathub.org/repo/flathub.flatpakrepo}}

Now reboot to complete setup

{{Note|graphical installation of Flatpak apps may not be possible with Alpine.}}

== Usage ==

To get all of the available options to use with the '''flatpak''' command run: '''flatpak --help''' or '''flatpak -h''',

=== Search ===

To search for applications run '''flatpak search <appplicationname>'''

Example:

~'''$''' flatpak search chromium

Name Description Application ID Version Branch Remotes
Chromium Web Browser The web browser from Chromium project org.chromium.Chromium 96.0.4664.93 stable flathub
Chromium B.S.U. Fast paced, arcade-style, top-scrolling space shooter net.sourceforge.chromium-bsu 0.9.16.1 stable flathub
ungoogled-chromium A lightweight approach to removing Google web service dependency com.github.Eloston.UngoogledChromium 96.0.4664.45 stable flathub


 

=== Install ===

To install a package run '''flatpak install <applicationname>'''

~'''$''' flatpak install com.github.Eloston.UngoogledChromium

Looking for matches…

com.github.Eloston.UngoogledChromium permissions:
ipc network cups pulseaudio wayland x11
devices file access [1] dbus access [2] bus ownership [3] system dbus access [4]

[1] /run/.heim_org.h5l.kcm-socket, home, xdg-run/pipewire-0
[2] org.freedesktop.FileManager1, org.freedesktop.Notifications, org.freedesktop.secrets, org.gnome.SessionManager
[3] org.mpris.MediaPlayer2.chromium.*
[4] org.freedesktop.Avahi, org.freedesktop.UPower

ID Branch Op Remote Download
1. com.github.Eloston.UngoogledChromium.Codecs stable i flathub < 1.1 MB
2. com.github.Eloston.UngoogledChromium.Locale stable i flathub < 112.8 kB
3. com.github.Eloston.UngoogledChromium stable i flathub < 119.0 MB

Proceed with these changes to the system installation? [Y/n]:


or if you dont know or dont want to type the exact package name:

~'''$''' flatpak install chromium

Looking for matches…
Similar refs found for ‘chromium’ in remote ‘flathub’ (system):

1) app/net.sourceforge.chromium-bsu/x86_64/stable
2) runtime/com.github.Eloston.UngoogledChromium.Codecs/x86_64/stable
3) runtime/org.chromium.Chromium.Codecs/x86_64/stable
4) app/org.chromium.Chromium/x86_64/stable
5) app/com.github.Eloston.UngoogledChromium/x86_64/stable

Which do you want to use (0 to abort)? [0-5]:


=== Remove ===

To remove a package run: '''flatpak remove <applicationname>'''

~'''$''' flatpak remove com.github.Eloston.UngoogledChromium

ID Branch Op
1. com.github.Eloston.UngoogledChromium stable r
2. com.github.Eloston.UngoogledChromium.Codecs stable r
3. com.github.Eloston.UngoogledChromium.Locale stable r

Proceed with these changes to the system installation? [Y/n]:


or if you dont know or dont want to type the exact package name:

~'''$''' flatpak remove chromium

Similar installed refs found for ‘chromium’:

1) app/com.github.Eloston.UngoogledChromium/x86_64/stable (system)
2) runtime/com.github.Eloston.UngoogledChromium.Codecs/x86_64/stable (system)
3) All of the above

Which do you want to use (0 to abort)? [0-3]:


== Developers ==

* [https://docs.flatpak.org/en/latest/available-runtimes.html Flatpak - available runtimes]

These are all hosted on [https://flathub.org/ Flathub.org].

== Troubleshooting ==

=== Permission errors ===

If you receive errors about permissions then you may need to add your user to the '''flatpak''' group.

{{Note|You need to log out and log back in or reboot for the group change(s) to take effect}}

=== Fixing audio issues ===

If you have a minimal setup and don't have access to audio devices you will need to set the XDG_RUNTIME_DIR variable. Save the following script in {{Path|/etc/profile.d/xdg_runtime_dir.sh}} and re-login to have it set up properly.

if test -z "${XDG_RUNTIME_DIR}"; then
export XDG_RUNTIME_DIR=/tmp/$(id -u)
fi

When you launch a Flatpak you will need to start pulseaudio as well:

{{Cmd|$ pulseaudio --start && flatpak run com.example.Example}}

=== Unable to upload files ===

If you are unable to upload files from the host, this maybe due to [https://docs.flatpak.org/en/latest/sandbox-permissions.html Flatpak sanbox] and you may have to manually add the authorization.

This can be done with the following commands:

{{Cmd|<nowiki>$ flatpak override ApplicationID --filesystem=/home/user/Downloads</nowiki>}}

Where ''ApplicationID'' is given by:

{{Cmd|$ flatpak list}}

For example:

{{Cmd|<nowiki>$ flatpak override org.signal.Signal --filesystem=/home/user/Downloads</nowiki>}}

== Links ==
* [https://flatpak.org/ Flatpak]
* [https://flathub.org/ Flathub]
* [https://winepak.github.io/ Winepak]

[[Category:Package Manager]]
[[Category: Desktop]]

KVM

2023-08-23T14:01:18Z

Faust: /* Networking */

[https://www.linux-kvm.org/page/Main_Page KVM] is an free and open source virtualization solution in a kernel module. Although it is often simply referred to as KVM, the actual hypervisor is [https://www.qemu.org QEMU]. QEMU runs from user-space, but can integrate with KVM, providing better performance by leveraging the hardware from kernel-space. QEMU can virtualize x86, PowerPC, and S390 guests, amongst others. [https://libvirt.org Libvirt] is a management framework that integrates with QEMU/KVM, [[LXC]], [[Xen_Dom0|Xen]] and others.

== Installation ==
The following commands provide '''libvirt''' as well as '''QEMU with emulation for x86_64''' and '''qemu-img''', a necessary component for using various disk formats such as qcow2. Without qemu-img, only raw disks are available. It can also convert images between several formats like vhdx and vmdk. It also provides the metapackage '''qemu-modules''', which provides subpackages needed for special features. In versions of Alpine before 3.13.0 these features were covered by '''QEMU with emulation for x86_64'''.
{{Cmd|<nowiki># apk add libvirt-daemon qemu-img qemu-system-x86_64 qemu-modules openrc
# rc-update add libvirtd</nowiki>}}

== Networking ==
By default, libvirt uses NAT for VM connectivity. If you want to use the default configuration, you need to load the tun module.
{{Cmd|# modprobe tun}}

Add tun to autostart:
{{Cmd|# echo "tun" >> /etc/modules-load.d/tun.conf}}

To make the tun module load on boot, use this command:
{{Cmd|# cat /etc/modules {{!}} grep tun {{!}}{{!}} echo tun >> /etc/modules}}

If you prefer bridging a guest over your Ethernet interface, you need to make a [[Bridge#Configuration_file|bridge]].

It's quite common to use bridges with KVM environments. But when IPv6 is used, Alpine will assign itself a link-local address as well as an SLAAC address in case there's a router sending Router Advertisements. You don't want this because you don't want to have the KVM host an IP address in every network it serves to guests. Unfortunately IPv6 can not just be disabled for the bridge via a sysctl configuration file, because the bridge might not be up when the sysctl config is applied during boot. What works is to put a post-up hook into the /etc/network/interfaces file like this:
auto brlan
iface brlan inet manual
bridge-ports eth1.5
bridge-stp 0
post-up ip -6 a flush dev brlan; sysctl -w net.ipv6.conf.brlan.disable_ipv6=1

== Management ==
For non-root management, you will need to add your user to the libvirt group.
{{Cmd|# addgroup user libvirt}}

You can use libvirt's virsh at the CLI. It can execute commands as well as run as an interactive shell. Read its manual page and/or use the "help" command for more info. Some basic commands are:

{{Cmd|<nowiki>virsh help
virsh list --all
virsh start $domain
virsh shutdown $domain</nowiki>
}}

The libvirt project provides a GUI for managing hosts, called virt-manager. It handles local systems as well as remote ones via SSH.
{{Cmd|<nowiki># apk add dbus polkit virt-manager font-terminus
# rc-update add dbus</nowiki>}}

In order to use libvirtd to remotely control KVM over ssh PolicyKit needs a .pkla informing it that this is allowed.
Write the following file to /etc/polkit-1/localauthority/50-local.d/50-libvirt-ssh-remote-access-policy.pkla
{{Cmd|<nowiki>[Remote libvirt SSH access]
Identity=unix-group:libvirt
Action=org.libvirt.unix.manage
ResultAny=yes
ResultInactive=yes
ResultActive=yes</nowiki>
}}

== Guest lifecycle management ==
The libvirt-guests service (available from Alpine 3.13.5) allows running guests to be automatically suspended or shut down when the host is shut down or rebooted.

The service is configured in /etc/conf.d/libvirt-guests. Enable the service with {{Cmd|# rc-update add libvirt-guests}}

== vfio ==

VFIO is more flexible way to do PCI passthrough. Let's suppose you want to use following ethernet card as PCI device in a VM.

# lspci | grep 02:00.0
02:00.0 Ethernet controller: Intel Corporation 82576 Gigabit Network Connection (rev 01)
# lspci -n -s 02:00.0
02:00.0 0200: 8086:10c9 (rev 01)

First, create ''/etc/mkinitfs/features.d/vfio.modules'' with the following content, so mkinitfs includes the VFIO modules in the initramfs.

kernel/drivers/vfio/vfio.ko.*
kernel/drivers/vfio/vfio_virqfd.ko.*
kernel/drivers/vfio/vfio_iommu_type1.ko.*
kernel/drivers/vfio/pci/vfio-pci.ko.*

Add ''vfio'' the the list of features in ''/etc/mkinitfs/mkinitfs.conf''.

Modify following file to instruct ''mkinitfs'' to load following module with the options and rebuild kernel ramdisk.

# cat /etc/modprobe.d/vfio.conf <<EOF
options vfio-pci ids=8086:10c9
options vfio_iommu_type1 allow_unsafe_interrupts=1
softdep igb pre: vfio-pci
EOF
# mkinitfs

Now we need to edit the "default_kernel_opts" and "modules" sections in the update-extlinux.conf file. Edit the "default_kernel_opts" to include ''intel_iommu=o iommu=pt'' for Intel platform (AMD uses ''amd_iommu=on''), and add the VFIO modules to the "modules" section.

# grep '^default_kernel_opts\|^modules' /etc/update-extlinux.conf
default_kernel_opts="quiet rootfstype=ext4 intel_iommu=on iommu=pt"
modules=sd-mod,usb-storage,ext4,raid1,vfio,vfio-pci,vfio_iommu_type1,vfio_virqfd

For syslinux/extlinux, run:

# update-extlinux

For GRUB (which [https://git.alpinelinux.org/aports/tree/main/grub/alpine-mkconfig.patch#n9 now also uses] the update-extlinux.conf if present), run:

# grub-mkconfig -o /boot/grub/grub.cfg

Reboot and check dmesg.

# grep -i -e DMAR -e IOMMU /var/log/dmesg
[ 0.343795] DMAR: Host address width 36
[ 0.343797] DMAR: DRHD base: 0x000000fed90000 flags: 0x1
[ 0.343804] DMAR: dmar0: reg_base_addr fed90000 ver 1:0 cap c90780106f0462 ecap f020e3
[ 0.343806] DMAR: RMRR base: 0x000000000ed000 end: 0x000000000effff
[ 0.343807] DMAR: RMRR base: 0x000000bf7ed000 end: 0x000000bf7fffff
[ 0.553830] iommu: Default domain type: Passthrough (set via kernel command line)
[ 0.902477] DMAR: No ATSR found
[ 0.902563] DMAR: dmar0: Using Queued invalidation
...
[ 0.903256] pci 0000:02:00.0: Adding to iommu group 12
...
[ 0.903768] DMAR: Intel(R) Virtualization Technology for Directed I/O

If you do not run libvirt VMs under ''root'' (''egrep '^#*user' /etc/libvirt/qemu.conf''), then you must have correct permission on ''/dev/vfio/<iommu_group>'', eg. ''/dev/vfio/12''. You have to tune ''/etc/mdev.conf'' or UDEV rules. Also note that if there are multiple PCI devices in the same iommu group, you always have to add all of them to the VM otherwise you'll get an error message like "Please ensure all devices within the iommu_group are bound to their vfio bus driver"

# virsh dumpxml vm01 | xmllint --xpath '//*/hostdev' -
<hostdev mode="subsystem" type="pci" managed="yes">
<driver name="vfio"/>
<source>
<address domain="0x0000" bus="0x02" slot="0x00" function="0x0"/>
</source>
<alias name="hostdev0"/>
<address type="pci" domain="0x0000" bus="0x00" slot="0x06" function="0x0"/>
</hostdev>
<hostdev mode="subsystem" type="pci" managed="yes">
<driver name="vfio"/>
<source>
<address domain="0x0000" bus="0x02" slot="0x00" function="0x1"/>
</source>
<alias name="hostdev1"/>
<address type="pci" domain="0x0000" bus="0x00" slot="0x08" function="0x0"/>
</hostdev>

If you directly use QEMU without libvirt and are trying to pass a GPU to your VM, you may get a "VFIO_MAP_DMA failed: Out of memory" error, when starting the VM as a non-root user. One way to fix it is to install the ''shadow'' package, and increase the amount of memory the user can lock via the ''/etc/security/limits.conf'' file:
{{Cmd|<nowiki># apk add shadow
# echo "youruser soft memlock RAMamount \
youruser hard memlock RAMamount" >> /etc/security/limits.conf
# reboot</nowiki>}}

Replace "youruser" with the user you wish to run the VM as, and "RAMamount" with how much RAM your VM will need (in KB). The exact amount may throw the same error in the end, so you probably want to increase this value by a few dozen MB (typically +40).

A lot of info on the [https://wiki.archlinux.org/index.php/PCI_passthrough_via_OVMF Archwiki article for PCI passthrough via OVMF].

[[Category:Virtualization]]

Talk:Configure a Wireguard interface (wg)

2023-08-22T17:03:40Z

Faust: /* Bringing up an interface using ifupdown-ng */

== Bringing up an interface using wg-tools ==

''Then load the module''

modprobe wireguard

''Add it to <code>/etc/modules</code> to automatically load it on boot.''

This does not seem to be necessary (any more)?

[[User:Anianz|Anianz]] ([[User talk:Anianz|talk]])

I can confirm that this was not necessary on 3.18 ([[User:faust|faust]]).

== Bringing up an interface using ifupdown-ng ==

The netifrc package is perfect for mounting the wg0 interface at boot in the specific case of using the plain wg command ( https://wiki.gentoo.org/wiki/Wireguard#netifrc ), but only available for the edge branch.

What is the right approach for loading the configuration file and mount the wg0 network interface, at startup in the stable branch?

Konki

Hi!
I am not sure if this is the "right" approach but I find it quite simple and clean, just add `post-up` and `post-down` commands in your `/etc/network/interfaces` file, see bellow:

❯ cat /etc/network/interfaces
auto lo
iface lo inet loopback
auto eth0
iface eth0 inet static
address 192.168.10.52
netmask 255.255.255.0
gateway 192.168.10.254
post-up wg-quick up /etc/wireguard/wg0.conf
post-down wg-quick down /etc/wireguard/wg0.conf

--[[User:Faust|Faust]] ([[User talk:Faust|talk]]) 17:03, 22 August 2023 (UTC)

Talk:Configure a Wireguard interface (wg)

2023-08-22T17:00:46Z

Faust: /* Bringing up an interface using ifupdown-ng */

== Bringing up an interface using wg-tools ==

''Then load the module''

modprobe wireguard

''Add it to <code>/etc/modules</code> to automatically load it on boot.''

This does not seem to be necessary (any more)?

[[User:Anianz|Anianz]] ([[User talk:Anianz|talk]])

I can confirm that this was not necessary on 3.18 ([[User:faust|faust]]).

== Bringing up an interface using ifupdown-ng ==

The netifrc package is perfect for mounting the wg0 interface at boot in the specific case of using the plain wg command ( https://wiki.gentoo.org/wiki/Wireguard#netifrc ), but only available for the edge branch.

What is the right approach for loading the configuration file and mount the wg0 network interface, at startup in the stable branch?

Konki

Hi, I am not sure if this is the "right" approach but I find it quite simple and clean, just add in `post-up` and `post-down` commands in your `/etc/network/interfaces` file, see bellow:

❯ cat /etc/network/interfaces
auto lo
iface lo inet loopback

auto eth0
iface eth0 inet static
address 192.168.10.52
netmask 255.255.255.0
gateway 192.168.10.254
post-up wg-quick up /etc/wireguard/wg0.conf
post-down wg-quick down /etc/wireguard/wg0.conf

Talk:Configure a Wireguard interface (wg)

2023-08-22T16:45:41Z

Faust:

Talk:Configure a Wireguard interface (wg)

2023-08-22T16:45:17Z

Faust: /* Bringing up an interface using wg-tools */

Sway

2023-08-21T08:25:20Z

Faust: wrong copy/paste...

[https://swaywm.org Sway] is a tiling [[Wayland]] compositor. It's a drop-in replacement for the i3 window manager.

== Installation ==

eudev:

{{Cmd|# setup-devd udev}}

Graphics drivers:

* [[Intel Video]]
* [[Radeon Video]]
* [[Nvidia Video]]
Add user to the input and video groups:

{{Cmd|# adduser $USER input
<nowiki>#</nowiki> adduser $USER video
}}

Install some TTF fonts:

{{Cmd|# apk add font-dejavu}}

seatd daemon:

{{Cmd|# apk add seatd
<nowiki>#</nowiki> rc-update add seatd
<nowiki>#</nowiki> rc-service seatd start
<nowiki>#</nowiki> adduser $USER seat
}}

Install sway:

{{Cmd|# apk add sway sway-doc
<nowiki>#</nowiki> apk add \ # Install optional dependencies:
xwayland \ # recommended for compatibility reasons
foot \ # default terminal emulator. Modify $term in config for a different one.
bemenu \ # wayland menu
swaylock swaylockd \ # lockscreen tool
swaybg \ # wallpaper daemon
swayidle # idle management (DPMS) daemon
}}

Configure [[Wayland#XDG_RUNTIME_DIR|XDG_RUNTIME_DIR]].

== Usage ==

For inter-program communication and functionality such as screensharing, install and enable [[D-Bus]] and PipeWire, see [[PipeWire]] and set <code>SWAYSOCK</code> environmental variable to the value exported by <code>sway</code>. In order to ensure that Pipewire and related services inherit the right environment variables, it is recommended to start these services via a process that is a direct descendant of sway itself.

Launch Sway with a D-Bus server available, use:

{{Cmd|dbus-run-session -- sway #prepend with exec in your login shell init script}}

== Configuration ==

An example config is provided at <code>/etc/sway/config</code>. Copy it to <code>~/.config/sway/config</code> and read through it to learn the default keybindings.
Sway configuration is mostly backwards-compatible with that of [[I3wm|i3]] and if you are looking for a solution for a specific issue, you may also try checking if it hasn't been provided for i3WM.

For additional information, start at <code>man 5 sway</code> and read the [https://github.com/swaywm/sway/wiki upstream wiki].

=== Firefox screensharing ===

For some programs, additional configuration is needed to launch them natively under Wayland and to support special features such as screen sharing.

To launch Firefox natively under Wayland and to enable support for screensharing, you need:

* Install and configure [[PipeWire]]
* Install xdg-desktop-portal and xdg-desktop-portal-wlr package
* Install wofi for screen selection
* Launch pipewire on sway startup:
<pre>
exec /usr/libexec/pipewire-launcher
</pre>
* xdg-desktop-portal will start xdg-desktop-portal-wlr when needed, but needs a few environment variables. Unless <code>dbus-daemon</code> is a descendant of the <code>sway</code> process, add to the sway config:
<pre>
exec dbus-update-activation-environment WAYLAND_DISPLAY XDG_CURRENT_DESKTOP=sway
</pre>
* Export the following variables:

{{Cmd|export MOZ_ENABLE_WAYLAND {{=}}"1"
export XDG_CURRENT_DESKTOP{{=}}sway
export QT_QPA_PLATFORM{{=}}"wayland-egl"
}}

=== Flatpaks ===

Due to their sandboxing, flatpaks require the use of a portal frontend (xdg-desktop-portal) and backends (such as xdg-desktop-portal-wlr, xdg-desktop-portal-gtk, xdg-desktop-portal-gnome) that implement the methods. When in doubt, install multiple backends. For more information on backends, see [https://github.com/flatpak/xdg-desktop-portal/#using-portals flatpak's page on the subject]. In addition to the steps under the "Firefox Screensharing" section, it may also be necessary to launch additional backends in your Sway config file. Otherwise, you may run into GDBus errors as your flatpak fails to interface with the portal. This can cause issues such as with opening your file directories from a flatpak application.

After installing different backends, you might need to add the relevant backends to your sway config file similarly to in the "Firefox Screensharing" section above. For example, an autostart section of your sway config file may include:
<pre>
exec /usr/libexec/xdg-desktop-portal-gtk
exec /usr/libexec/xdg-desktop-portal-wlr
exec /usr/libexec/xdg-desktop-portal-gnome
</pre>

This is only needed if they are not started automatically via other means.

=== Scaling for high resolution screens ===

Without further configuration, program interfaces might be too small to use on high resolution screens.

==== Via sway ====

Sway supports the per-display configuration of

* fractional (e.g., 1.5x), and
* integer scaling (e.g., 2x)

However, fractional scaling is discouraged due to both the performance impact and the blurry output it produces. In this case, where 1x scaling is too small and 2x scaling is too large, program-specific GTK/QT based scaling is recommended. See below.

To enable Sway scaling, the user can first preview different scaling factors with <code>wdisplays</code> package. Note the output name (eDP-1, LVDS-1) and try apply scaling factors such as 1 and 2. To make changes permanent, add

<pre>
output <name> scale <factor>
</pre>

to ~/.config/sway/config.

==== Via GTK/Qt ====

{{Cmd|# for GTK-based programs such as firefox and emacs:
export GDK_DPI_SCALE{{=}}2

<nowiki>#</nowiki> for QT-based programs
export QT_WAYLAND_FORCE_DPI{{=}}"physical"
<nowiki>#</nowiki> or if still too small, use a custom DPI
export QT_WAYLAND_FORCE_DPI{{=}}192 # 2x scaling
export QT_QPA_PLATFORM{{=}}"wayland-egl"
}}

=== Make clipboard content persistent ===
By default the clipboard content does not persist after terminating the program: you copy some text from Firefox and then exit Firefox, the copied text is also lost.

Install clipman from test repo and add the following to sway config:

<pre>
exec wl-paste --type text/plain --watch clipman store --histpath="~/.local/state/clipman-primary.json"
bindsym $mod+h exec clipman pick --tool wofi --histpath="~/.local/state/clipman-primary.json"
</pre>

=== Firefox picture-in-picture mode/floating windows ===
Add this to your sway config file (modify the numeric values to suit your needs and your display):
<pre>
for_window [app_id="firefox" title="^Picture-in-Picture$"] floating enable, move position 877 450, sticky enable, border none
</pre>

=== Screenshots ===
A simple tool that works well under Wayland is Grimshot. Example keybindings:
<pre>
bindsym Print exec grimshot copy area
bindsym Shift+Print exec grimshot copy screen
bindsym Control+Print exec grimshot save area ~/Pictures/$(date +%d-%m-%Y-%H-%M-%S).png
bindsym Control+Shift+Print exec grimshot save screen ~/Pictures/$(date +%d-%m-%Y-%H-%M-%S).png
</pre>

See [https://github.com/swaywm/sway/wiki/Useful-add-ons-for-sway the sway wiki's article] for a list of screenshot tools.

=== Start with NumLock enabled ===
Add this to your sway config file:
<code>input type:keyboard xkb_numlock enabled</code>

=== Change cursor theme and size ===
Add to your sway config:
<pre>
seat seat0 xcursor_theme my_cursor_theme my_cursor_size
</pre>
You can inspect their values with <code>echo $XCURSOR_SIZE</code> and <code>echo $XCURSOR_THEME</code>. If reloading your config does not result in change, try logging out and in.
{{Note|Wayland uses client-side cursors. It is possible that applications do not evaluate the values of <code>$XCURSOR_SIZE</code> and <code>$XCURSOR_THEME</code>.}}

=== Start as a service ===
Although this is not necessary, you may write an init script like the following:

{{Cat|/etc/init.d/sway|#!/sbin/openrc-run

description{{=}}"Sway Compositor"

command{{=}}"/usr/bin/sway"
command_args{{=}}""

pidfile{{=}}"/run/sway.pid"

start_stop_daemon_args{{=}}"--background --pidfile ${pidfile}"

depend() {
need localmount
after elogind
use seatd dbus
}
}}

Then run

{{Cmd|# chmod +x /etc/init.d/sway}}

and

{{Cmd|# rc-update add sway default}}

Make sure you have {{Pkg|elogind}} installed or specify another service, like your display/login manager after which the sway service will run.

=== Custom keyboard layout ===

Since wayland does not support setxkbmap, you will also need to add similar content to your ''/usr/share/X11/xkb/rules/evdev.xml'', after <code></modelList></code> and after <code><layoutList></code>:
<pre>
<layout>
<configItem>
<name>[the name of your layout, same as the name of the file in /usr/share/X11/xkb/symbols]</name>
<shortDescription>[usually just two letters]</shortDescription>
<description>[description of your layout]</description>
<countryList>
<iso3166Id>US</iso3166Id>
<iso3166Id>NO</iso3166Id>
</countryList>
<languageList>
<iso639Id>eng</iso639Id>
</languageList>
</configItem>
</layout>

</pre>
Then, to enable for all keyboards, navigate to the input section of ''~/.config/sway/config'' and modify it to
<pre>
input * {
xkb_layout "my_layout"
}
</pre>
If you have enabled <code>xkb_numlock</code>, include this setting inside those braces as well.

== Troubleshooting ==

If you encounter any issues, try running <code>sway -Vc /etc/sway/config</code>. It will run sway with the default config file and set the output to be more verbose. It is generally a good idea to track your config files with git (when and if at all you use a remote repository for them, keep it private for security reasons).

=== Firefox (Flatpak) and/or GTK apps ===
==== Disappearing cursor ====
You may need to get an icon pack and possibly a theme from [https://www.pling.com/browse?cat=107&ord=latest Pling store] and set <code>GTK_THEME</code> environmental variable. Alternatively you can install a theme for all users (search [https://pkgs.alpinelinux.org/ Alpine Linux Packages] for ''*-icon-theme'') using <code>apk add</code>.

==== Missing file picker/cannot download ====

Go to ''about:config'' and set <code>widget.use-xdg-desktop-portal.file-picker</code> to 0.

=== Failing to start under certain graphics cards/multiple wlroots stacked windows spawning upon start ===
As of Dec 31 2022, [https://developer.nvidia.com/docs/drive/drive-os/latest/linux/sdk/common/topics/window_system_stub/Gnome-WaylandDesktopShellSupport136.html Nvidia still doesn't fully support Wayland]. Therefore, the possible solutions are as outlined in the link, or setting your WLR_BACKENDS environmental variables to <code>drm,libinput</code> or <code>x11</code> (add libinput here as well if you cannot use your mouse and keyboard after starting Sway). The latter also works for AMD/ATI cards ('''make sure to install libinput first''').

=== Sway socket not detected ===

See [[Sway#Installation|Installation]] for instructions on how to set this environmental variable. This issue may occur with terminal multiplexers, such as [[Tmux terminal multiplexer|tmux]]

=== Steam games launched via Proton crash before creating a window ===

Instead of just using the in-Steam menu to install and select a Proton version, try installing the flatpak community build for Proton onto your system. There are several versions, depending on your desired stability, and the experimental version available in Flathub is called "com.valvesoftware.Steam.CompatibilityTool.Proton-Exp". After you install your chosen version, go into Steam to specify compatibility tool for a game as usual. The installed community build will now be an option. Select that and try launching the game again.

[[Category:Desktop]]
[[Category:Window Managers]]