Configuration¶

Coneshare's behavior is controlled by two primary configuration files:

• .env: Controls the deployment environment, such as service ports and system resource checks.
• app.env: Configures the Coneshare application itself, including the site domain and email settings.

Environment Configuration (.env)¶

You can customize the installation script and Docker Compose environment by creating a .env file.

docker compose version

To override the default settings, create /opt/coneshare/.env with your desired values. This will override any defaults set within the coneshare-compose/.env file. Commonly modified parameters include:

# The host port that the service is bound to.
CONESHARE_BIND=8999

# The minimum memory (in MB) required by the installation script.
MIN_RAM_HARD=4000

# The minimum CPU cores required by the installation script.
MIN_CPU_HARD=2

Change Service Port¶

By default, Coneshare binds to port 8999. To change this, set CONESHARE_BIND to your desired port in /opt/coneshare/.env.

# Example: Change the port to 8080
CONESHARE_BIND=8080

Adjust System Resource Checks¶

The installation script checks for at least 2 CPU cores and 4 GB of RAM. If your system has fewer resources, you can lower these checks in /opt/coneshare/.env.

# Example: Lower requirements to 1 CPU and 2 GB RAM
MIN_CPU_HARD=1
MIN_RAM_HARD=2000

Application Configuration (app.env)¶

The app.env file, located at /opt/coneshare/app.env, is generated during installation and contains settings specific to the Coneshare application.

Site Domain¶

You must configure SITE_DOMAIN to match your server's public-facing IP address or domain name. This is critical for generating correct share links.

Edit /opt/coneshare/app.env and set the variable:

# Example: Using an IP address
SITE_DOMAIN=http://10.8.1.1:8999

# Example: Using a domain name
SITE_DOMAIN=https://coneshare.example.com

Email Sending¶

Features like password resets require a configured email service. To enable this, add your SMTP server credentials to /opt/coneshare/app.env.

EMAIL_BACKEND=django.core.mail.backends.smtp.EmailBackend
EMAIL_HOST=smtp.mail.com
EMAIL_PORT=587
EMAIL_USE_TLS=True
[email protected]
EMAIL_HOST_PASSWORD=your-email-password
[email protected]

Below is an example for a Gmail account:

EMAIL_HOST=smtp.gmail.com
EMAIL_PORT=587
EMAIL_USE_TLS=True
[email protected]
EMAIL_HOST_PASSWORD=your-app-password
[email protected]

After adding the email configuration, restart the service.

Document Preview Settings¶

To optimize resource usage on smaller self-hosted machines, Coneshare allows you to configure document preview engines and toggle preview capabilities. This is particularly useful for reducing CPU and memory consumption.

Edit /opt/coneshare/app.env to configure the following settings:

# The engine used to render PDF documents. Options: pdfjs, server_pages
PDF_PREVIEW_ENGINE=pdfjs

# Enable/disable Microsoft Office document preview. Options: true, false
ENABLE_OFFICE_PREVIEW=false

Preview Engines (PDF_PREVIEW_ENGINE)¶

• pdfjs: Renders PDF documents client-side using PDF.js in the browser.

  • Pros: Extremely lightweight on the server (low CPU/RAM usage), making it perfect for smaller servers (e.g., 2 CPU, 2 GB RAM).
  • Cons: Page-level analytics and visual watermarking are best-effort (applied client-side) and can be bypassed by advanced users.

• server_pages (Default): Renders PDF pages into images on the server.

  • Pros: Enables highly secure server-rendered visual watermarks and precise page-level analytics.
  • Cons: High resource utilization (CPU and memory spikes during page rendering). Previews are rendered lazily on demand when first accessed.

Office Document Preview (ENABLE_OFFICE_PREVIEW)¶

• false: Disables preview for Microsoft Office files (Word, Excel, PowerPoint), making them download-only. This eliminates the need for running a LibreOffice conversion pipeline, keeping server overhead to a minimum.
• true (Default): Enables Office file preview by converting them to PDF and rendering pages on the server.
  • Requirements: Must be paired with PDF_PREVIEW_ENGINE=server_pages. Startup configuration will reject combinations where ENABLE_OFFICE_PREVIEW=true but PDF_PREVIEW_ENGINE=pdfjs.
  • Resource Profiles: Recommended only for higher-capacity deployments (minimum 4 CPU cores, 4 GB RAM) due to the heavy background conversion workload.

Virus Scanning Settings¶

Coneshare can scan incoming files uploaded via public File Request links before they are stored in your workspace. This feature utilizes ClamAV to prevent malware from being introduced into your document libraries.

To configure virus scanning, add or update the following settings in /opt/coneshare/app.env:

# Enable/disable virus scanning. Options: true, false
MALWARE_SCAN_ENABLED=false

# ClamAV service configuration
CLAMAV_HOST=clamav
CLAMAV_PORT=3310

# Scan timeout in milliseconds
MALWARE_SCAN_TIMEOUT_MS=10000

# Behavior if the scanner is offline/errors. Options: closed, open
MALWARE_SCAN_FAIL_MODE=closed

Settings Reference¶

• MALWARE_SCAN_ENABLED: Toggles malware scanning for public File Requests.
• CLAMAV_HOST: Hostname or IP address of the ClamAV service (defaults to clamav when running within the Docker Compose network).
• CLAMAV_PORT: Port number for ClamAV (default is 3310).
• MALWARE_SCAN_TIMEOUT_MS: Time limit in milliseconds for scanning requests before timing out.
• MALWARE_SCAN_FAIL_MODE: Determines scanner fail-safe behavior:
  • closed (Recommended): Rejects uploads if the scanner is unavailable or errors out.
  • open: Allows uploads even if the scanner is offline or encounters an error.

For details on enabling and deploying the ClamAV scanner service container, see the File Request Virus Scan guide.