Nextcloud: Difference between revisions

From NixOS Wiki
imported>Onny
Add note on managing secrets
imported>Onny
Add section on secret management
Line 15: Line 15:


After that you will be able to login into your Nextcloud instance at http://localhost with user <code>root</code> and password <code>test123</code> as configured above.  
After that you will be able to login into your Nextcloud instance at http://localhost with user <code>root</code> and password <code>test123</code> as configured above.  
Please note that this example is for demonstration purpose and passwords should be not supplied like this, consider reference a local file containing the secrets and use a [[Comparison of secret managing schemes|secret management tool]].


== Configuration ==
== Configuration ==
Line 114: Line 112:


Test mails can be send via administration interface in the menu section "Basic settings".
Test mails can be send via administration interface in the menu section "Basic settings".
=== Secrets management ===
Do not suply passwords, hashes or keys via <code>extraOptions</code> option, since they will be copied into the world-readable Nix store. Instead reference a JSON file containing secrets using the <code>secretFile</code> option.
<syntaxHighlight lang="nix">
services.nextcloud = {
  [...]
  secretFile = "/etc/nextcloud-secrets.json";
};
environment.etc."nextcloud-secrets.json".text = ''
  {
    "passwordsalt": "12345678910",
    "secret": "12345678910",
    "instanceid": "10987654321"
    "redis": {
      "password": "secret"
    }
  }
'';
</syntaxHighlight>
Consider using a  [[Comparison of secret managing schemes|secret management tool]] instead of referencing an unencrypted local secrets file.


== Maintenance ==
== Maintenance ==

Revision as of 15:35, 12 June 2023

Nextcloud (wikipedia:en:Nextcloud) is a self-hosted web groupware and cloud software, offering collaboration on files, managing calendar events, contacts and tasks.

Installation

A minimal example to get a Nextcloud running on localhost should look like this

/etc/nixos/configuration.nix
services.nextcloud = {
  enable = true;
  package = pkgs.nextcloud26;
  hostName = "localhost";
  config.adminpassFile = "${pkgs.writeText "adminpass" "test123"}";
};

After that you will be able to login into your Nextcloud instance at http://localhost with user root and password test123 as configured above.

Configuration

Be sure to read the Nextcloud module's documentation in the NixOS Manual.

Enable apps

Some apps which are already packaged on NixOS can be installed directly with the following example configuration

/etc/nixos/configuration.nix
services.nextcloud = {                
  enable = true;                   
  [...]
  package = pkgs.nextcloud26;
  extraApps = {
    inherit (pkgs.nextcloud26Packages.apps)
      news
      contacts
      calendar
      tasks
    ;
  };
  extraAppsEnable = true;
};

The apps mail, news and contacts will be installed and enabled in your instance automatically. Note that the Nextcloud version specified in package and extraApps need to match on of the stable Nextcloud versions available in the NixOS repository.

To manually fetch and install packages, you need to add them via the helper script fetchNextcloudApp by specifing the release tarball as url and the correct checksum. Both are available for example in the official Nextcloud app store. Note that in this case the app package version and checksum has to be updated manually in case there is a new release.

/etc/nixos/configuration.nix
services.nextcloud = {                
  enable = true;                   
  [...]
  extraApps = {
    mail = pkgs.fetchNextcloudApp rec {
      url = "https://github.com/nextcloud-releases/mail/releases/download/v1.14.1/mail-v1.14.1.tar.gz";
      sha256 = "sha256-sQUsYC3cco6fj9pF2l1NrCEhA3KJoOvJRhXvBlVpNqo=";
    };
    contacts = pkgs.fetchNextcloudApp rec {
      url = "https://github.com/nextcloud-releases/contacts/releases/download/v4.2.2/contacts-v4.2.2.tar.gz";
      sha256 = "sha256-eTc51pkg3OdHJB7X4/hD39Ce+9vKzw1nlJ7BhPOzdy0=";
    };
  };
  extraAppsEnable = true;
};

Alternatively apps can be manually installed via the app store integrated in your Nextcloud instance by navigating in the profile menu to the site "Apps".

SSL

If you would like to setup Nextcloud with Let's Encrypt TLS certificates (or certs from any other certificate authority) make sure to set services.nextcloud.https = true; and to enable it in the nginx-vHost.

/etc/nixos/configuration.nix
services.nextcloud = {                
  enable = true;                   
  [...]
  hostName = "example.org";
  https = true;
};

services.nginx.virtualHosts.${config.services.nextcloud.hostName} = {
  forceSSL = true;
  enableACME = true;
};

Caching

Redis can be enabled as a performant caching backend using following configuration. This will bring faster page loads to your Nextcloud instance.

/etc/nixos/configuration.nix
services.nextcloud = {                
  enable = true;        
  # New option since NixOS 23.05
  configureRedis = true;
  caching.apcu = false;
  [...]
};

Mail delivery

Besides various mail delivery options and settings, mail clients like Msmtp can be used to configure mail delivery for Nextcloud. This can be useful for sending registration mails or system notifications etc. To configure Nextcloud to use a local mail delivery daemon, we configure mail_smtpmode to sendmail and a further sending mode.

services.nextcloud = {
  [...]
  extraOptions = {
    mail_smtpmode = "sendmail";
    mail_sendmailmode = "pipe";
  };
};

Test mails can be send via administration interface in the menu section "Basic settings".

Secrets management

Do not suply passwords, hashes or keys via extraOptions option, since they will be copied into the world-readable Nix store. Instead reference a JSON file containing secrets using the secretFile option.

services.nextcloud = {
  [...]
  secretFile = "/etc/nextcloud-secrets.json";
};

environment.etc."nextcloud-secrets.json".text = ''
  {
    "passwordsalt": "12345678910",
    "secret": "12345678910",
    "instanceid": "10987654321"
    "redis": {
      "password": "secret"
    }
  }
'';

Consider using a secret management tool instead of referencing an unencrypted local secrets file.

Maintenance

Upgrade

As you can see on the package search, there is no default nextcloud package. Instead you have to set the current version in services.nextcloud.package. As soon a major version of Nextcloud gets unsupported, it will be removed from nixpkgs as well.

Upgrading then consists of these steps:

  1. nextcloud-occ maintenance:mode --on
  2. Increment the version of services.nextcloud.package in your config by 1 (leaving out a major version is not supported)
  3. nixos-rebuild switch
  4. nextcloud-occ maintenance:mode --off

In theory, your nextcloud has now been upgraded by one version. NixOS attempts nextcloud-occ upgrade, if this succeeds without problems you don't need to do anything. Check journalctl to make sure nothing horrible happened. Go to the /settings/admin/overview page in your nextcloud to see whether it recommends further processing, such as database reindexing or conversion.

Clients

Nextcloudcmd

nextcloudcmd is a terminal client performing only a single sync run and then exits. The following example command will synchronize the local folder /home/myuser/music with the remote folder /music of the Nextcloud server https://nextcloud.example.org.

# nix shell nixpkgs#nextcloud-client -h --user example --password test123 --path /music /home/myuser/music https://nextcloud.example.org

The argument -h will enable syncing hidden files. For demonstration purpose username and password are supplied as an argument. This is a security risk and shouldn't be used in production.

Using Home Manager we can create a systemd-timer which automatically runs the sync command every hour for the user myuser.

/etc/nixos/configuration.nix
home-manager.users.myuser = {
  
  home.file.".netrc".text = ''default
    login example
    password test123
  '';

  systemd.user = {
    services.nextcloud-autosync = {
      Unit = {
        Description = "Auto sync Nextcloud";
        After = "network-online.target"; 
      };
      Service = {
        Type = "simple";
        ExecStart= "${pkgs.nextcloud-client}/bin/nextcloudcmd -h -n --path /music /home/myuser/music https://nextcloud.example.org"; 
        TimeoutStopSec = "180";
        KillMode = "process";
        KillSignal = "SIGINT";
      };
      Install.WantedBy = ["multi-user.target"];
    };
    timers.nextcloud-autosync = {
      Unit.Description = "Automatic sync files with Nextcloud when booted up after 5 minutes then rerun every 60 minutes";
      Timer.OnUnitActiveSec = "60min";
      Install.WantedBy = ["multi-user.target" "timers.target"];
    };
    startServices = true;
  };

};

The login credentials will be written to a file called .netrc used nextcloudcmd for authentication to the Nextcloud server.

Tips and tricks

Change default listening port

In case port 80 is already used by a different application or you're using a different web server than Nginx, which is used by the Nextcloud module, you can change the listening port with the following option:

/etc/nixos/configuration.nix
services.nginx.virtualHosts."localhost".listen = [ { addr = "127.0.0.1"; port = 8080; } ];

Troubleshooting

Reading php logs

The default Nextcloud setting is to log to syslog. To read php logs simply run

# journalctl -t Nextcloud

Nextcloud-setup error: Nextcloud is not installed

You get the message

  U Wed Jul  3 06:15:06 2019 p3 nextcloud-cron.service Nextcloud[9374]: {cron} {"Exception":"Exception","Message":"Not installed","Code":0,"Trace":[{"file":"\/nix\/store\/9c58nxa9mzzg93ppwq2jlynpf4vsbd30-nextcloud-15.0.8\/lib\/base.php","line":660,"function":"checkInstalled","class":"OC","type":"::","args":[]},{"file":"\/nix\/store\/9c58nxa9mzzg93ppwq2jlynpf4vsbd30-nextcloud-15.0.8\/lib\/base.php","line":1068,"function":"init","class":"OC","type":"::","args":[]},{"file":"\/nix\/store\/9c58nxa9mzzg93ppwq2jlynpf4vsbd30-nextcloud-15.0.8\/cron.php","line":41,"args":["\/nix\/store\/9c58nxa9mzzg93ppwq2jlynpf4vsbd30-nextcloud-15.0.8\/lib\/base.php"],"function":"require_once"}],"File":"\/nix\/store\/9c58nxa9mzzg93ppwq2jlynpf4vsbd30-nextcloud-15.0.8\/lib\/base.php","Line":277,"CustomMessage":"--"}

Then you run into known issue.

Known issues