Skip to content

instructions.md

Latest commit

 

History

History
90 lines (56 loc) · 13.2 KB

instructions.md

File metadata and controls

90 lines (56 loc) · 13.2 KB
Raw

Nextcloud

Nextcloud auto-generates an admin password on first install and posts a critical task to show it to you. Save the password before dismissing — it is shown once.

Documentation

What you get on StartOS

  • A Web UI for Nextcloud — files, calendar, contacts, photos, talk, and the full Nextcloud app ecosystem.
  • A WebDAV endpoint at /remote.php/dav/ for desktop and mobile sync clients.
  • A bundled PostgreSQL database and Valkey cache; you do not configure either.
  • Trusted domains, caching, file locking, and proxy headers are pre-configured and kept in sync with your StartOS hostnames on every start.

Getting set up

  1. After install, Nextcloud posts a critical task Get Admin Credentials. Run it and copy the admin username and password to a password manager — the password is shown only once.
  2. Start the service and open the Web UI.
  3. Log in with admin and the password from step 1.
  4. From the admin user menu, create your day-to-day user accounts and tune Nextcloud's settings (email, sharing, apps, etc.) through the Nextcloud admin pages.

Using Nextcloud

Web UI

Open the Web UI interface to reach Nextcloud's web interface. From there you install apps from the Nextcloud App Store, manage users and groups, and use Files, Calendar, Contacts, Photos, Talk, and anything else you install.

Keeping an existing .onion address after an update

If your server carried Nextcloud over from StartOS 0.3.5, updating frees its old network bindings and reattaches an unused .onion address to the Web UI while keeping its hostname. Install or update Tor to 0.4.9.13:1 or newer to complete that reattachment; Nextcloud can update without Tor and waits for it to become available. Use the updated Web UI or WebDAV interface address when reconnecting clients: the reattached onion uses plain HTTP, which Tor encrypts in transit.

WebDAV

Point a Nextcloud desktop or mobile client (or any WebDAV client) at the WebDAV interface address to sync files. Use the username and password of the Nextcloud account you want to sync, not the admin account if it's a personal device.

Actions

  • Configure — set the default locale, default phone region, how long deleted files are kept before Nextcloud removes them for good (Delete Files in Trash — by default they are kept at least 30 days and then cleared only when disk space runs short, so trash can pile up on a server with room to spare), the UTC start hour of Nextcloud's nightly maintenance window for background jobs, a toggle to stop seeding new user accounts with Nextcloud's default skeleton files (sample documents, photos, README), and Relay Talk Calls Through Coturn (see below).
  • External Storage — surface another StartOS service's storage as a folder in your Nextcloud Files, using Nextcloud's built-in External Storage app. The action lists a dropdown for each supported service you have installed (NextExplorer → a /NextExplorer folder showing its Files location, plus one folder for each other location, such as /NextExplorer (FileBrowser) for files you imported from File Browser; FileBrowser Quantum → a /FileBrowser folder). NextExplorer creates its Files location the first time it starts, so start it once if you want that folder to appear here. Each dropdown is Not mounted (off), Available to all users, or Available to specific users (which then lets you pick exactly which Nextcloud users see it). The folder is read-write, so you can move files out of it into Nextcloud. Who can see it is decided here, not in NextExplorer: every Nextcloud user you make it available to sees all of NextExplorer's locations, even if you have limited which NextExplorer accounts can open them. Nextcloud looks for locations when it starts, so after adding one — importing from File Browser, pointing another service at a location of its own, or with NextExplorer's Add Location action — restart Nextcloud to see it here. If you rename a location with NextExplorer's Rename Location action, Nextcloud sees a new folder after its next restart, so favourites and tags you set under the old name do not carry over; the files themselves are never touched. Nextcloud must be running to run this action (it reads your live user list). Files other services add to NextExplorer or FileBrowser Quantum appear automatically when you open the folder — so NextExplorer acts as the shared hub: point any service that should be visible in Nextcloud at NextExplorer.
  • Reset Admin Password — pick a member of Nextcloud's admin group and generate a new random password. Use this if the admin password is lost or you want to rotate it.
  • Disable Maintenance Mode (Maintenance group) — runs occ maintenance:mode --off. Brief maintenance mode after an update or restart is normal — wait at least 15 minutes before resorting to this. It asks you to confirm first, since it takes Nextcloud out of maintenance mode even if an update is still running. Nextcloud version updates now run as part of the StartOS update step and roll back cleanly if they fail, so you should rarely need this.
  • Disable Non-default Apps (Maintenance group) — disables every enabled app that Nextcloud does not ship, keeping the bundled set plus Calendar and Contacts. Use this if a third-party app has broken the UI with an Internal Server Error. The result lists what was disabled, and separately anything that could not be, so a single stuck app does not stop the rest. Stable apps must then be re-enabled individually from the Nextcloud Apps page.
  • Scan Files (Maintenance group) — queues a background rebuild of the file cache after files are synced into Nextcloud externally (rclone, rsync, SFTP, etc.). Run this if externally synced files appear stale, show wrong sizes, or are missing from search. It asks you to confirm first, since it restarts the service. On a large library the scan can take many minutes; progress shows as the File Scan health check on the service status page, and StartOS posts a notification when it finishes.
  • Repair (Maintenance group) — queues a background run of Nextcloud's built-in repair routine, fixing database inconsistencies, stale cache entries, and broken shares, and clearing the missing-indices and mimetype-migration warnings in administration settings. Run this if files appear missing, shares return errors, or after a crash or abrupt shutdown. It asks you to confirm first, since it restarts the service. Progress shows as the Repair health check on the service status page, and StartOS posts a notification when it finishes. The same work runs on its own after every update, shown as the Post-Update Maintenance health check, with a notification only if it fails.
  • Download Machine Learning Models for Recognize (App Commands group) — queues a background download of the ML models the Recognize app needs for object and face detection (~1-2 GB). Install the Recognize app from the Nextcloud App Store first. Progress shows on the service status page while the download is in flight, and StartOS posts a notification when it finishes.
  • Index Media for Memories (App Commands group) — queues a background re-index of media for the Memories app. Memories normally re-indexes itself every five minutes; only run this to force an immediate re-index (it asks you to confirm first, since it restarts the service). Install the Memories app and select a media path first. StartOS posts a notification when the re-index finishes.
  • Setup Map for Memories (App Commands group) — queues a background download of map data (~2-3 GB) and a re-index so the Memories app can reverse-geotag your photos. Install the Memories app first. Avoid running this alongside other heavy work on a low-resource device. StartOS posts a notification when it finishes.

Talk calls that won't connect

Nextcloud Talk places calls directly between the two participants, which fails when both ends sit behind NAT or a strict firewall — the call rings, then drops or stays silent. Turning on Relay Talk Calls Through Coturn in the Configure action gives those calls a relay to fall back on.

Two things have to be in place first:

  1. Install the Talk app in Nextcloud, from Apps in the Nextcloud web UI. It also has to stay enabled — a Nextcloud major upgrade disables any app that has no compatible release yet, and relaying is not applied again until you update Talk and re-enable it.
  2. Install the separate Coturn service from the StartOS marketplace, start it, and give it a public domain of its own, as its own instructions describe.

Then turn the toggle on. Until all three are done, calls still work wherever a direct connection is possible, and nothing reports the missing relay as an error.

Nextcloud is what tells Talk where the relay is, so there is nothing to enter in Talk's own admin settings — and nothing you have already entered there gets overwritten. Talk's default STUN server, stun.nextcloud.com:443, is also left in place; remove it under Administration settings → Talk if you would rather every part of call setup stayed on your own server.

Editing documents

Nextcloud on its own shows your documents but cannot edit them. To edit in the browser, install one of the two office services from the Marketplace and connect it:

  1. Install Collabora Online, unless you have a specific reason for the other one — see below. ONLYOFFICE Docs is in the Community Registry, so you would need that registry added to your server to find it.
  2. Run the Office Suite action here and pick the one you installed. Nextcloud installs the app it needs for it — Nextcloud Office (Collabora) or ONLYOFFICE — and points itself at the service.

Switching between the two later is the same step: pick the other one, and Nextcloud sets up its app and switches the previous one off. Only one of them may be enabled — with both on, Nextcloud stops opening Word, Excel and PowerPoint files in either. If you ever remove or switch off the app yourself, this service's page will say so and name the one to turn back on.

If you pick a document server that is still starting, or one you have not installed yet, this service's page shows it waiting, and the setup finishes on its own once the server is ready.

Documents, spreadsheets and presentations then open in the browser from Files, and several people can edit the same file at once. The editor is served from your Nextcloud address, so it works the same on your local network, a public domain, or Tor.

Which one to choose

Collabora Online for almost everyone. It uses roughly a quarter of the memory — a gigabyte or so against the four ONLYOFFICE asks for — and opens more kinds of file, including Visio, WordPerfect and Apple iWork documents that ONLYOFFICE cannot. It edits Word, Excel and PowerPoint files perfectly well.

ONLYOFFICE Docs only for a large body of style-heavy documents that keeps going back to Microsoft Office. Its native format is the same one Word and Excel use, so it saves a file back exactly as it found it. Collabora is built on LibreOffice, which reads a Word file into its own model and writes it out again; nothing is lost — the text, tables, images, links, footnotes and page layout all survive — but it writes the formatting out in its own way, spelling out on each paragraph what the document had left to its styles. You would not see a difference on screen. You would see one if a colleague later opened that file in Word and changed a style, because the parts Collabora spelled out no longer follow it.

For one document that costs you nothing — you would never notice, and you could fix it by hand. It adds up when there are hundreds of them, when the styles are doing real work (a house template, a legal or academic format), and when the files keep cycling back to Word. Short of that, the memory is better spent elsewhere.

Limitations

  • No arbitrary host directory mounts. You can surface another StartOS service's files with the External Storage action (NextExplorer or FileBrowser Quantum), and you can attach remote storage (S3, WebDAV, SMB, etc.) through Nextcloud's built-in External Storage app. StartOS does not expose arbitrary host directories to the container.
  • No built-in SMTP. Configure email under Nextcloud's Administration settings → Basic settings → Email server.
  • A file over 1 GiB uploads only in chunks. The Nextcloud web page and the desktop and mobile apps send large files in 100 MiB chunks, so their uploads are limited only by free disk space. A WebDAV client that sends a whole file in one request is refused above 1 GiB. The PHP memory limit is 1024 MB. Neither limit is user-configurable.
  • Update one major Nextcloud version at a time. Nextcloud only supports upgrading a single major version per step. An update that would jump more than one major version at once is refused with a clear message before anything changes; install the release it names from the version list, then update again. Keep the service updated regularly rather than letting several releases pile up.