Skip to content

Config file updates

We’ve encountered several problems while maintaining this software, and I feel we’d better make a breaking change to the config file. We’ll provide a tool for migrating the config files, and hopefully there will be no hassle for server admins. (Sorry for many irregular operations!)

Plans

We are planning to change the config directory name from .config to config, change the config file format from YAML to TOML, and move most of the setting items from the control panel to the config file (server blocks/mutes and relays will be kept on the control panel).

Current config directory:

.config
├── LICENSE
├── docker.env
├── docker_example.env
├── default.yml
├── dev.example.yml
└── example.yml

New config directory:

config
├── LICENSE
├── container.env
├── container.example.env
├── config.toml
├── dev.example.toml
└── example.toml

Why

  • Some things can only be configured on the control panel (and admin API).
    • Let’s say you want to modify the object storage config. You may want to have some maintenance window and stop your server while updating the config so you can work calmly and ensure that no one uploads new files before completing the modification. - This is impossible. You need to edit the object storage config on the control panel, which requires you to run your server during maintenance. You can’t ensure no user uploads new files to an undesired location.
  • Some things can be configured in the config file and the control panel (i.e., there are multiple sources for a single config).
    • but frankly, most contributors don’t care about/are not aware of it (and we don’t want to take care of such things). Also, there are no clear rules for these settings (e.g., which one is prioritized if you set different values in the config file and control panel?)
  • There is a good chance that old items no longer in effect are still in your config file, especially if you have hopped between Misskey forks or have been running your server for several years.
    • Such items are simply ignored, so it doesn’t hurt but could be misleading.
  • We’d like to rename some items to more descriptive names.
  • The current design makes it difficult to refactor the backend.
  • We’re using the Rust crate serde_yaml, which has been deprecated. The toml crate is more common and well-maintained. (and I think TOML is easier to read and write than YAML)
  • Aside from compatibility with other Misskey forks, is there any reason we should hide the .config directory?
  • What does the file name default.yml mean? This is a config file, not a default value or something.

Notes (for server admins)

  • You will need to restart your server to apply config changes.
    • Implementing a live reload is possible, but we need to make the config variable mutable. This requires more careful coding, and we don’t expect that you need to change the config frequently, so it’s out of our plans. Let’s post “restarting the server to apply config changes” and be patient for a minute.
  • Hosted server admins (non-selfhosters) may have trouble with this change because they do not have access to the config file.
    • Hosted users should consult with your system admin and vice versa.
  • You don’t have to remove the old config files. Keeping them may be helpful if you migrate your server to other Misskey forks (you can keep the old .config directory as an archive).
  • We haven’t come up with a good name for the new config file. config/config.toml is okay but is a bit weird. Do you have any suggestions?
  • Any feedback on this plan is welcome, as long as it’s constructive.
Edited by naskya