{"id":17095932,"url":"https://github.com/travier/fedora-coreos-matrix","last_synced_at":"2025-03-23T17:42:51.427Z","repository":{"id":48902349,"uuid":"323303575","full_name":"travier/fedora-coreos-matrix","owner":"travier","description":"Butane config to host a Matrix homeserver on Fedora CoreOS (Caddy + Let's Encrypt + Synapse + PostgreSQL + element-web)","archived":false,"fork":false,"pushed_at":"2023-12-18T15:13:41.000Z","size":90,"stargazers_count":44,"open_issues_count":3,"forks_count":7,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-03-20T11:12:21.702Z","etag":null,"topics":["fedora-coreos","ignition-configs","matrix-homeserver","synapse"],"latest_commit_sha":null,"homepage":"","language":"Makefile","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/travier.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2020-12-21T10:32:52.000Z","updated_at":"2025-02-21T22:23:31.000Z","dependencies_parsed_at":"2023-12-18T16:46:12.098Z","dependency_job_id":"7754a4cf-79e5-421c-8821-a35df8be7b19","html_url":"https://github.com/travier/fedora-coreos-matrix","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/travier%2Ffedora-coreos-matrix","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/travier%2Ffedora-coreos-matrix/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/travier%2Ffedora-coreos-matrix/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/travier%2Ffedora-coreos-matrix/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/travier","download_url":"https://codeload.github.com/travier/fedora-coreos-matrix/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245144021,"owners_count":20568049,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["fedora-coreos","ignition-configs","matrix-homeserver","synapse"],"created_at":"2024-10-14T14:44:11.670Z","updated_at":"2025-03-23T17:42:51.398Z","avatar_url":"https://github.com/travier.png","language":"Makefile","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Butane config to host a Matrix homeserver on Fedora CoreOS\n\nExample Butane config to host a Matrix homeserver on Fedora CoreOS. This will\nsetup:\n  * nginx with Let's Encrypt for HTTPS support\n  * Synapse with PostgreSQL and elements-web\n\nFor this setup, you need a domain name and two sub-domains:\n  * example.tld\n  * matrix.example.tld\n  * chat.example.tld\n\nFor Let's Encrypt support, those domains must be configured beforehand to\nresolve to the IP address that will be assigned to your server. If you do not\nknow what IP address will be assigned to your server in advance, you might want\nto use another ACME challenge method to get Let's Encrypt certificates (see\n[DNS Plugins][plugins]).\n\nIf you already have certificates from Let's Encrypt or another provider, see\nthe [in progress PR](https://github.com/travier/fedora-coreos-matrix/pull/10)\nfor an alternative with existing certificates.\n\n## How to use\n\nTo generate the Ignition configs, you need `make` and [Butane][butane]:\n\nThen, you need to provide values for each variable in the secrets file:\n\n```\n$ cp secrets.example secrets\n$ ${EDITOR} secrets\n# Fill in values not marked as generated by Synapse\n```\n\n### Configuring Synapse\n\nThe Synapse configuration requires to setup a few secrets, you can generate\nthese secret using the following command :\n\n```\n$ source secrets\n$ mkdir generated\n$ podman run -it --rm -v $PWD/generated:/data:z \\\n      -e SYNAPSE_SERVER_NAME=\"${DOMAIN_NAME}\" \\\n      -e SYNAPSE_REPORT_STATS=yes \\\n      docker.io/matrixdotorg/synapse:latest \\\n      generate\n```\nThis command will generate 3 files\n\n- `generated/homeserver.yaml`\n- `generated/my.matrix.host.log.config`\n- `generated/my.matrix.host.signing.key`\n\n#### Configuration\n\nA template version of the generated `homeserver.yaml` is included in\n`template/synapse/homeserver.yaml`.\n\nFirst we want to replace the secrets with values that were generated for you by\nSynapse.\nNote that the generated secrets may contain characters which are currently not\nhandled well by the Makefile. Problematic characters include `\u0026` and `#` and\npossibly others. Always manually verify that the final config files contain\nthe correct secrets.\nSee [isssue #14](https://github.com/travier/fedora-coreos-matrix/issues/14)\nfor details.\n\nIn the `secrets` file, edit the following variables:\n\n- `SYNAPSE_REGISTRATION_SHARED_SECRET`, with the content of\n  `registration_shared_secret` in `homeserver.yaml`\n- `SYNAPSE_MACAROON_SECRET_KEY`, with the content of `macaroon_secret_key` in\n  `homeserver.yaml`\n- `SYNAPSE_FORM_SECRET`, with the content of `form_secret` in `homeserver.yaml`\n- `SYNAPSE_SIGNING_KEY`, with the content of `my.matrix.host.signing.key`\n- `SYNAPSE_REGISTRATION`, whether or not to enable open registration\n\n```\nSSH_PUBKEY=\"ssh-rsa AAAA...\"\nPOSTGRES_PASSWORD=a_passpharse_for_my_database\nDOMAIN_NAME=my.matrix.domain\nEMAIL=root@example.com\nSYNAPSE_REGISTRATION_SHARED_SECRET=a_very_long_string_generated_by_synapse\nSYNAPSE_MACAROON_SECRET_KEY=a_very_long_string_generated_by_synapse\nSYNAPSE_FORM_SECRET=a_very_long_string_generated_by_synapse\nSYNAPSE_SIGNING_KEY=a_key_generated_by_synapse\nSYNAPSE_REGISTRATION=false\n```\n\nIf you wish to change other Synapse settings you can edit directly\n`template/synapse/homeserver.yaml` and `template/synapse/synapse.log.config` to\nchange the logging configuration.\n\n### System and container updates\n\nBy default, Fedora CoreOS systems are updated automatically to the latest\nreleased update. This makes sure that the system is always on top of security\nissues (and updated with the latest features) wthout any user interaction\nneeded. The containers, as defined in the systemd units in the config, are\nupdated on each service startup. They will thus be updated at least once after\neach system update as this will trigger a reboot approximately every two week.\n\nTo maximise availability, you can set an [update strategy][updates] in\nZincati's configuration to only allow reboots for updates during certain\nperiods of time.  For example, one might want to only allow reboots on week\ndays, between 2 AM and 4 AM UTC, which is a timeframe where reboots should have\nthe least user impact on the service. Make sure to pick the correct time for\nyour timezone as Fedora CoreOS uses the UTC timezone by default.\n\nSee this example config that you can append to `config.bu`:\n\n```\n[updates]\nstrategy = \"periodic\"\n\n[[updates.periodic.window]]\ndays = [ \"Mon\", \"Tue\", \"Wed\", \"Thu\", \"Fri\" ]\nstart_time = \"02:00\"\nlength_minutes = 120\n```\n\n## Generate the ignition configuration\n\nFinally, you can generate the final Ignition config with:\n\n```\n$ make\n```\n\nYou are now ready to deploy your Fedora CoreOS Matrix home server.\n\n## Deploying\n\nSee the [Fedora CoreOS docs][deploy] for instructions on how to use this\nIgnition config to deploy a Fedora CoreOS instance on your prefered platform.\n\n## Registering new users\n\nRegistration is disabled by default for security and to avoid mistakes. If you\nwant to create an instance with open registration, you can set the\n`SYNAPSE_REGISTRATION` value to `true` in your `secrets` file.\n\nOtherwise, you can still add accounts to an instance by running the following\ncommand directly on the server:\n\n```\n$ sudo podman run --rm --tty --interactive \\\n      --pod=matrix \\\n      -v /var/srv/matrix/synapse:/data:z,ro \\\n      --entrypoint register_new_matrix_user \\\n      docker.io/matrixdotorg/synapse:latest \\\n      -c /data/homeserver.yaml http://127.0.0.1:8008\n```\n\n## PostgreSQL major version updates\n\nMajor PostgreSQL version updates require manual intervention to dump the\ndatabase with the current version and then import it in the new version. We\nthus can not use the `latest` tag for this container image and manual\nintervention will be required approximately once a year to update the PostreSQL\ncontainer version.\n\nSee this example to dump the current database and import it when moving from\nversion 13 to 14:\n\n```\n# Stop Synapse server to ensure no-one is writing to the database\n$ systemctl stop synapse\n\n# Dump the database\n$ mkdir /var/srv/matrix/postgres.dump\n$ cat /etc/postgresql_synapse\n$ podman run --read-only --pod=matrix --rm --tty --interactive \\\n      -v /var/srv/matrix/postgres.dump:/var/data:z \\\n      docker.io/library/postgres:13 \\\n      pg_dump --file=/var/data/dump.sql --format=c --username=synapse \\\n      --password --host=localhost synapse\n\n# Stop the PostgreSQL container\n$ systemctl stop postgres\n\n# Keep existing database as backup\n$ mv /var/srv/matrix/postgres /var/srv/matrix/postgres.bak\n$ mkdir /var/srv/matrix/postgres\n\n# Edit the PostgreSQL unit to update the container version\n$ vi /etc/systemd/system/postgres.service\n\n# Start the new PostgreSQL container\n$ systemctl start postgres\n\n# Import the database. Make sure to use the new PostgreSQL container image\n$ podman run --read-only --pod=matrix --rm --tty --interactive \\\n      -v /var/srv/matrix/postgres.dump:/var/data:ro,z \\\n      docker.io/library/postgres:14 \\\n      pg_restore --username=synapse --password --host=localhost \\\n      --dbname=synapse /var/data/dump.sql\n\n# Start Synapse again\n$ systemctl start synapse\n\n# Cleanup once everything is confirmed working\n$ rm -rf /var/srv/matrix/postgres.dump /var/srv/matrix/postgres.bak\n```\n\n[deploy]: https://docs.fedoraproject.org/en-US/fedora-coreos/getting-started/\n[plugins]: https://certbot.eff.org/docs/using.html#dns-plugins\n[updates]: https://coreos.github.io/zincati/usage/updates-strategy/#periodic-strategy\n[butane]: https://coreos.github.io/butane/getting-started/#getting-butane\n\n## License\n\nSee [LICENSE](LICENSE) or [CC0](https://creativecommons.org/public-domain/cc0/).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftravier%2Ffedora-coreos-matrix","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftravier%2Ffedora-coreos-matrix","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftravier%2Ffedora-coreos-matrix/lists"}