How-to: Nextcloud Full Text Search with the Cloudron Elasticsearch community package

[andreasdueren]

This guide configures Nextcloud Full Text Search (FTS) to use Elasticsearch over the Cloudron-internal app network.

The Elasticsearch REST API is not public. The public app URL exposes only a minimal health endpoint; Nextcloud connects directly to Elasticsearch on internal port 9200.

1. Install Elasticsearch from the community catalog

In Cloudron, open:

App Store → Settings → Community Apps

Add this catalog URL:

https://git.due.ren/andreas/elasticsearch-cloudron/-/raw/main/CloudronVersions.json

Or install through the Cloudron CLI:

cloudron install \
  --versions-url https://git.due.ren/andreas/elasticsearch-cloudron/-/raw/main/CloudronVersions.json \
  --location elasticsearch.example.com

Installing from this catalog makes the app community-tracked, allowing Cloudron to discover later package releases through its normal update mechanism.

Allocate at least 4 GB RAM where possible. The package sizes Elasticsearch's JVM heap from the app memory limit.

2. Obtain the internal Elasticsearch address and credential

Open the Elasticsearch app's Web Terminal and run:

hostname
cat /app/data/credentials.txt

hostname prints the Cloudron app ID. This is the internal hostname that other Cloudron apps can resolve for the lifetime of this installed app.

Use the app-ID hostname, not the container IP. Container IP addresses are not a supported configuration value and can change.

The internal Elasticsearch endpoint is:

http://<APP_ID_HOSTNAME>:9200

For example:

http://210f8b84-f417-4697-80b7-efefd18e7329:9200

The generated password is also available at:

/app/data/secrets/elastic_password

Treat it as a secret. A Cloudron app that has both this password and the internal hostname can query Elasticsearch.

Important: If the Elasticsearch app is removed and installed again, it receives a new app ID. Update the Nextcloud elastic_host configuration after such a migration.

3. Enable the Nextcloud FTS apps

Open the Nextcloud app's Web Terminal and run:

sudo -u www-data php /app/code/occ app:enable fulltextsearch
sudo -u www-data php /app/code/occ app:enable fulltextsearch_elasticsearch
sudo -u www-data php /app/code/occ app:enable files_fulltextsearch

4. Configure Nextcloud

Set the FTS platform and the index name:

sudo -u www-data php /app/code/occ config:app:set \
  fulltextsearch app_navigation --value "1"

sudo -u www-data php /app/code/occ config:app:set \
  fulltextsearch search_platform \
  --value "OCA\\FullTextSearch_Elasticsearch\\Platform\\ElasticSearchPlatform"

sudo -u www-data php /app/code/occ config:app:set \
  fulltextsearch_elasticsearch elastic_index --value "nextcloud"

Set the Elasticsearch connection. The password must be URL-encoded if it contains URL-reserved characters such as @, :, /, ?, #, or %.

sudo -u www-data php /app/code/occ config:app:set \
  fulltextsearch_elasticsearch elastic_host \
  --value "http://elastic:URL_ENCODED_PASSWORD@APP_ID_HOSTNAME:9200"

Replace:

• URL_ENCODED_PASSWORD with the generated Elasticsearch password, URL-encoded where necessary.
• APP_ID_HOSTNAME with the value returned by hostname in the Elasticsearch app.

Example shape:

http://elastic:REDACTED@210f8b84-f417-4697-80b7-efefd18e7329:9200

5. Test and build the index

sudo -u www-data php /app/code/occ fulltextsearch:test
sudo -u www-data php /app/code/occ fulltextsearch:index

The first indexing run can take time, depending on the number and size of files.

Elasticsearch's built-in german analyzer is available. No separate ICU plugin is required for the standard German analyzer.

6. Verify Elasticsearch and the public boundary

Inside the Elasticsearch app:

curl -u elastic:$(cat /app/data/secrets/elastic_password) \
  http://localhost:9200/_cat/indices?v

You should see the nextcloud index after indexing.

From outside the Cloudron, verify that Elasticsearch API routes are not public:

curl -i https://elasticsearch.example.com/_cat/indices

Expected result:

HTTP 404
{"status":"not_found"}

The harmless public health endpoint should remain available:

curl -i https://elasticsearch.example.com/health

Expected result:

HTTP 200
{"status":"green","service":"elasticsearch-cloudron"}

Security and operational notes

• Elasticsearch REST runs on internal port 9200; it is not routed through the public Cloudron reverse proxy.
• The public Cloudron httpPort serves only /health.
• The Elasticsearch transport port 9300 has no external Cloudron port mapping.
• HTTP CORS is disabled by default.
• Elasticsearch data persists in /app/data; routine package updates do not normally require a re-index.
• Do not use container IP addresses in Nextcloud configuration.

[girish]

Thanks for the write up.

@andreasdueren do you think the elasticsearch package can make use of https://docs.cloudron.io/packaging/manifest#backupcommand ? Since filesystem backup is not atomic on Cloudron, this might bring more consistency to the elasticsearch backups (since elastic is a "database").

[andreasdueren]

@girish Thanks, didn't know about this feature and implemented what I understood to be best practice in the latest version:

The package now uses Cloudron’s backupCommand to create an Elasticsearch filesystem snapshot before Cloudron copies /app/data.

That snapshot is created by Elasticsearch, waits for SUCCESS, and is included in the normal Cloudron app backup under:

/app/data/snapshots

So the current situation is:

Cloudron backup
├── normal /app/data filesystem copy
└── completed Elasticsearch snapshot

If the restored raw Elasticsearch data starts normally, nothing else is required. If it does not, the Elasticsearch snapshot is the supported recovery source.

I considered stopping Elasticsearch for the entire Cloudron filesystem-copy phase to make the raw copy consistent, but that would add backup downtime and probably be less robust than Elasticsearch’s own snapshot mechanism.

[girish]

@andreasdueren there is a companion command called restoreCommand which will restore from the snapshot into the filesystem . You also don't need to back up the raw elastic files, you can use persistentDirs

[andreasdueren]

@girish That was the missing piece, thank you. I mistakenly had concluded from the backupCommand docs alone that there was no restore-side hook. restoreCommand is documented, it just isn't cross-linked from backupCommand.

One thing I hit that may be a bug in 9.2.0: the docs state the backupCommand container shares the app container's network namespace, so services on localhost are reachable. On my install that did not work. curl to 127.0.0.1:9200 failed with exit code 7 (connection refused / could not connect) during backupCommand, on two separate package releases, including one with --retry 30 --retry-delay 2 --retry-connrefused retrying for roughly a minute. The identical command run inside the live app container via cloudron exec succeeded immediately, and the app was healthy throughout.

I worked around it for now by having backupCommand talk to the live container over a Unix socket in /app/data/run instead of TCP. Happy to provide logs or a minimal reproducer if that's unexpected. restoreCommand shouldn't care since the app isn't running at that point, but backupCommand does depend on it.

[girish]

@andreasdueren good catch, I have pushed doc fix. The networking issue is fixed in Cloudron 10 , yes