elasticsearch-cloudron/INSTALL.md

# Elasticsearch Cloudron Package Installation

This guide explains how to install the Elasticsearch package on your Cloudron instance.

## Prerequisites

- A Cloudron instance (version 7.0.0 or later)
- Administrative access to your Cloudron

## Installation Steps

### Method 1: Using the Cloudron App Store (When Available)

1. Log in to your Cloudron dashboard
2. Go to the App Store
3. Search for "Elasticsearch"
4. Click Install
5. Follow the on-screen instructions

### Method 2: Manual Installation

1. Download the latest package from the releases page
2. Log in to your Cloudron dashboard
3. Go to Settings -> Apps -> Install with File
4. Select the downloaded package file
5. Follow the on-screen instructions

## Post-Installation

After installation:

1. Check the app logs to ensure Elasticsearch has started correctly
2. Note the generated password from the logs or from `/app/data/credentials.txt`
3. Configure your other Cloudron apps to connect to Elasticsearch using the format: `http://elastic:<password>@localhost:9200`
4. (Recommended) Verify the bundled `analysis-icu` plugin (required by Nextcloud’s full-text search):  
   ```bash
   curl -X GET -u elastic:<password> "localhost:9200/_nodes/plugins?pretty"
   ```  
   The output should list `analysis-icu` before you kick off `occ fulltextsearch:index`. If you need additional plugins, rebuild this package with the desired plugin baked into the image (runtime installation is blocked by Elasticsearch 9’s filesystem restrictions).

## Troubleshooting

- If Elasticsearch fails to start, check the app logs for error messages
- Ensure your Cloudron has sufficient resources available
- If you encounter disk space issues, consider increasing the app's storage allocation

## Support

For support, please create an issue on the package's GitHub repository or contact the package maintainer. 

## Integration with Nextcloud

If you want to use this Elasticsearch package with Nextcloud's Full-Text Search functionality, follow these steps:

### Prerequisites

1. Ensure you have the following Nextcloud apps installed:
   - Full-Text Search
   - Full-Text Search - Elasticsearch Platform
   - Any content provider app (e.g., Full-Text Search - Files)

### Configuration Steps

#### 1. Find Your Elasticsearch Password

Check the Elasticsearch app logs to find the generated password:

```bash
# From the Cloudron dashboard, view the Elasticsearch app logs
# Look for lines containing "Password: " after Elasticsearch has started
# Or check the file at /app/data/credentials.txt within the container
```

#### 2. Create Elasticsearch Index (Optional)

You can manually create an Elasticsearch index using curl:

```bash
# Connect using localhost (from within another Cloudron app)
curl -X PUT "http://elastic:<your-password>@localhost:9200/nextcloud"
```

This creates an index named "nextcloud" that will be used for Nextcloud integration.

For general purposes, you can create other indices as needed:

```bash
# Create a general-purpose index named "cloud"
curl -X PUT "http://elastic:<your-password>@localhost:9200/cloud"
```

You can verify the indices were created successfully with:

```bash
curl "http://elastic:<your-password>@localhost:9200/_cat/indices"
```

Alternatively, you can let Nextcloud create and configure the index automatically using the OCC command:

```bash
cd /app/code
php occ fulltextsearch_elasticsearch:configure '{"elastic_host":"http://elastic:<your-password>@localhost:9200","elastic_index":"nextcloud"}'
```

#### 3. Configure Nextcloud

Access the Nextcloud CLI:

```bash
# From the Cloudron dashboard, click on your Nextcloud app
# Navigate to "Settings" → "Terminal" to access the CLI
# Or use the Cloudron CLI command: cloudron exec --app your-nextcloud-app
```

Run the following commands in the Nextcloud CLI:

```bash
# Using the OCC command (preferred method)
cd /app/code
php occ config:app:set fulltextsearch_elasticsearch allow_self_signed_cert --value=false
php occ config:app:set fulltextsearch_elasticsearch elastic_ssl --value=false
```

#### 4. Configure the Elasticsearch Connection

Still in the Nextcloud CLI, configure the Elasticsearch connection:

```bash
php occ fulltextsearch_elasticsearch:configure '{"elastic_host":"http://elastic:<your-password>@localhost:9200","elastic_index":"nextcloud"}'
```

Replace `<your-password>` with the password you found in step 1.

#### 5. Initialize the Index

Create and initialize the Elasticsearch index:

```bash
php occ fulltextsearch:index
```

For a full reindex of all content, use:

```bash
php occ fulltextsearch:index -f
```

#### 6. Test the Configuration

Verify that the connection works:

```bash
php occ fulltextsearch:test
```

### Authentication Details

Use the following credentials for Elasticsearch:
- Username: `elastic`
- Password: The generated password from `/app/data/credentials.txt`

### Troubleshooting

If you encounter connection errors:
- Ensure you're using port 9200 (not 9300)
- Use HTTP instead of HTTPS in the connection URL
- In Cloudron, use `localhost` instead of IP addresses for app-to-app communication
- Check that the Elasticsearch app is running

#### Testing Connectivity

You can test connectivity to Elasticsearch from another Cloudron app with:

```bash
curl -v http://elastic:<your-password>@localhost:9200
```

If successful, you should see a JSON response with Elasticsearch information.

#### Advanced Configuration

In some cases, you might need to modify additional Elasticsearch settings. You can do this via the elasticsearch.yml file, which is stored in `/app/data/config/elasticsearch.yml` within the Elasticsearch app container.