{"id":35888261,"url":"https://github.com/liketheduck/supernote-private-cloud-docker","last_synced_at":"2026-01-15T09:00:44.803Z","repository":{"id":330737882,"uuid":"1123784043","full_name":"liketheduck/supernote-private-cloud-docker","owner":"liketheduck","description":"Self-hosted Supernote Private Cloud with Docker Compose, HTTPS, and email support","archived":false,"fork":false,"pushed_at":"2025-12-27T16:28:57.000Z","size":19,"stargazers_count":5,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-12-29T13:22:15.405Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":null,"has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/liketheduck.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-12-27T16:04:02.000Z","updated_at":"2025-12-29T01:27:45.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/liketheduck/supernote-private-cloud-docker","commit_stats":null,"previous_names":["liketheduck/supernote-private-cloud-docker"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/liketheduck/supernote-private-cloud-docker","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/liketheduck%2Fsupernote-private-cloud-docker","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/liketheduck%2Fsupernote-private-cloud-docker/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/liketheduck%2Fsupernote-private-cloud-docker/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/liketheduck%2Fsupernote-private-cloud-docker/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/liketheduck","download_url":"https://codeload.github.com/liketheduck/supernote-private-cloud-docker/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/liketheduck%2Fsupernote-private-cloud-docker/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28447922,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-15T05:05:00.929Z","status":"ssl_error","status_checked_at":"2026-01-15T05:04:58.515Z","response_time":62,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-01-09T01:00:43.771Z","updated_at":"2026-01-15T09:00:44.798Z","avatar_url":"https://github.com/liketheduck.png","language":null,"funding_links":[],"categories":["Resources"],"sub_categories":["Tools"],"readme":"# Supernote Private Cloud - Docker Setup\n\nA secure, self-hosted Supernote Private Cloud deployment using Docker Compose with HTTPS, persistent storage, and email support.\n\n## Architecture\n\nThis setup deploys a 4-service stack:\n\n- **MariaDB 10.6.24**: Database server for Supernote data\n- **Redis 7.4.7**: Cache layer with password authentication\n- **Notelib 6.9.3**: Supernote library service for document conversion (note viewing)\n- **Supernote Service 25.12.17**: Main application with HTTPS, REST API, and WebSocket support\n\nAll services communicate through a private Docker bridge network (`supernote-net`). The MariaDB and Redis services are not exposed to host ports by default—only the Supernote service is accessible via HTTPS. MariaDB can optionally be exposed for integrations like [supernote-apple-reminders-sync](https://github.com/liketheduck/supernote-apple-reminders-sync).\n\n## Prerequisites\n\n### Docker\n\n**For macOS:** Install [Docker Desktop](https://www.docker.com/products/docker-desktop/) or [OrbStack](https://orbstack.dev/).\n\n- **Apple Silicon (M1-M4):** OrbStack is recommended. The Supernote images are x86-based and require emulation on ARM Macs. OrbStack has a lighter footprint and better x86 emulation performance than Docker Desktop. It's a drop-in replacement.\n- **Intel Macs:** Either option works well.\n\n**For Linux:** Install [Docker Engine](https://docs.docker.com/engine/install/) (includes the `docker compose` command).\n\n## Quick Start\n\n### 1. Clone and Configure\n\n```bash\n# Clone the repository\ngit clone https://github.com/liketheduck/supernote-private-cloud-docker.git\ncd supernote-private-cloud-docker\n\n# Copy example files\ncp docker-compose.example.yml docker-compose.yml\ncp .env.example .env\n\n# Edit .env with your settings (generate secure passwords)\nnano .env\n```\n\n### 2. Generate Secure Passwords\n\n```bash\n# Generate random passwords for .env\nopenssl rand -base64 24  # Use for MYSQL_ROOT_PASSWORD\nopenssl rand -base64 24  # Use for MYSQL_PASSWORD\nopenssl rand -base64 24  # Use for REDIS_PASSWORD\n```\n\n### 3. Update Volume Paths\n\nEdit `docker-compose.yml` and update the volume paths to match your system. The example uses relative paths (`./data/`) which work for most setups.\n\n### 4. Generate SSL Certificate\n\n```bash\n# Create cert directory\nmkdir -p cert\n\n# Generate self-signed certificate (valid 10 years)\n# Includes CA extensions so mobile devices can trust it\nopenssl req -x509 -nodes -days 3650 -newkey rsa:2048 \\\n  -keyout cert/server.key \\\n  -out cert/server.crt \\\n  -subj \"/CN=your-hostname.local\" \\\n  -addext \"basicConstraints=critical,CA:TRUE\" \\\n  -addext \"keyUsage=critical,keyCertSign,cRLSign,digitalSignature,keyEncipherment\" \\\n  -addext \"subjectAltName=DNS:your-hostname.local,DNS:localhost,IP:127.0.0.1\"\n```\n\n**Customize for your setup:**\n- Replace `your-hostname.local` with your server's actual hostname (in both `-subj` and `-addext`)\n- Add your server's IP address(es) to `subjectAltName` (e.g., `IP:192.168.1.100`)\n- Include all hostnames and IPs you'll use to access the server\n\n**Example with multiple IPs:**\n```bash\nopenssl req -x509 -nodes -days 3650 -newkey rsa:2048 \\\n  -keyout cert/server.key \\\n  -out cert/server.crt \\\n  -subj \"/CN=my-server.local\" \\\n  -addext \"basicConstraints=critical,CA:TRUE\" \\\n  -addext \"keyUsage=critical,keyCertSign,cRLSign,digitalSignature,keyEncipherment\" \\\n  -addext \"subjectAltName=DNS:my-server.local,DNS:localhost,IP:192.168.1.100,IP:127.0.0.1\"\n```\n\n**For mobile/partner apps:** After setup, you'll need to install the certificate on your devices. See [HTTPS certificate errors](#https-certificate-errors) in Troubleshooting for iOS and Android instructions.\n\n### 5. Start Services\n\n```bash\ndocker compose up -d\n```\n\nCheck status:\n```bash\ndocker compose ps\n```\n\n## Storage Structure\n\n```\n./\n├── data/\n│   ├── mariadb/          # Database files\n│   ├── redis/            # Cache persistence\n│   ├── supernote/        # User documents\n│   ├── recycle/          # Deleted files\n│   └── convert/          # Document conversions\n├── cert/                 # HTTPS certificates\n└── logs/\n    ├── cloud/            # Application cloud logs\n    ├── app/              # Application service logs\n    └── web/              # Nginx web server logs\n```\n\n## Network Configuration\n\n| Port | Type | Purpose |\n|------|------|---------|\n| **19443** | HTTPS | Primary access (secure) |\n| **19072** | HTTP | Fallback/redirect to HTTPS |\n| **18072** | WebSocket | Document auto-sync between devices |\n| **3306** | TCP | MariaDB (optional, for integrations) |\n\n## Initial Setup\n\n### 1. Access the Web Interface\n\n```\nhttps://your-hostname.local:19443\n```\n\nOr via IP address:\n```\nhttps://YOUR_IP_ADDRESS:19443\n```\n\n### 2. Device Connection\n\nOn your Supernote device:\n- **Server**: Your hostname or IP address\n- **Port**: `19443`\n- **Enable \"Allow insecure connections\"** (for self-signed certificate)\n\n### 3. Email Configuration (Optional)\n\nEmail is required for user registration. Configure via the web interface:\n\n1. Click **\"Email Settings\"** button\n2. Set:\n   - **SMTP Server**: `smtp.gmail.com`\n   - **Port**: `465`\n   - **Email**: Your email address\n   - **Password**: App-specific password (not your regular password)\n   - **Encryption Type**: `SSL`\n3. Click **Save** and **Test**\n\n**For Gmail users:**\n1. Enable 2-factor authentication on your Google account\n2. Go to [myaccount.google.com/apppasswords](https://myaccount.google.com/apppasswords)\n3. Generate an app password\n4. Use the 16-character password in email settings\n\nAlternatively, copy and configure `supernote-email-init.sql.example` to pre-populate email settings.\n\n### 4. User Registration\n\n1. Click **Register** in the web interface\n2. Enter your email (will receive verification code)\n3. Enter the code from the email\n4. Complete registration\n\n## Configuration Files\n\n### `.env` - Environment Variables\n\n```\nMYSQL_ROOT_PASSWORD=     # Root database password\nMYSQL_USER=supernote     # Database user\nMYSQL_PASSWORD=          # Database user password\nREDIS_PASSWORD=          # Redis password\nDOMAIN_NAME=             # Hostname/domain for HTTPS\nSSL_CERT_NAME=server.crt # Certificate filename\nSSL_KEY_NAME=server.key  # Key filename\n```\n\n### `docker-compose.yml` - Service Configuration\n\nServices are configured with:\n- **Health checks**: Automatic restart on failure\n- **Dependencies**: Services wait for required services to be healthy\n- **Restart policy**: `unless-stopped` (survives host reboot)\n- **Networks**: Private `supernote-net` bridge (services isolated from other Docker containers)\n- **Notelib alias**: The notelib container must have the network alias `notelib` (the supernote-service has this hostname hardcoded)\n\n## Commands\n\n### Stop Services\n```bash\ndocker compose down\n```\n\n### View Logs\n```bash\n# All services\ndocker compose logs -f\n\n# Specific service\ndocker compose logs -f supernote-service\n```\n\n### Database Backup\n```bash\n# Backup\ndocker compose exec supernote-mariadb mysqldump -uroot -p$MYSQL_ROOT_PASSWORD supernotedb \u003e backup.sql\n\n# Restore\ndocker compose exec -T supernote-mariadb mysql -uroot -p$MYSQL_ROOT_PASSWORD supernotedb \u003c backup.sql\n```\n\n## Troubleshooting\n\n### Services won't start\n\n```bash\n# Check container logs\ndocker compose logs supernote-service\n\n# Verify network is created\ndocker network ls | grep supernote-net\n\n# Check disk space\ndf -h\n```\n\n### HTTPS certificate errors\n\nThis is normal with a self-signed certificate. Your browser will warn you—accept the certificate exception to continue.\n\n**For mobile/partner apps**, you must install the certificate on your device:\n\n**iOS:**\n1. Transfer `server.crt` to your device (AirDrop, email, etc.)\n2. Open the file → Settings will prompt to install the profile\n3. Go to **Settings → General → VPN \u0026 Device Management** → Install the profile\n4. Go to **Settings → General → About** → scroll to bottom → **Certificate Trust Settings**\n5. Enable full trust for your certificate\n\n**Android:**\n1. Transfer `server.crt` to your device\n2. **Settings → Security → Encryption \u0026 credentials → Install a certificate → CA certificate**\n\n**Note:** The certificate must be generated with `CA:TRUE` (see Generate SSL Certificate section) for mobile devices to show the trust option.\n\n### Email not sending\n\nCheck email configuration via **Email Settings** \u003e **Test**. Common issues:\n\n- **Wrong app password**: Use the 16-character password from your email provider, not your regular password\n- **2FA not enabled**: Gmail app passwords require 2-factor authentication\n- **Port blocked**: Some networks block port 465. Try port 587 with TLS instead of SSL\n\n### Database connection errors\n\n```bash\n# Verify MariaDB is healthy\ndocker compose logs supernote-mariadb | grep -i error\n\n# Check data directory permissions\nls -la ./data/mariadb/\n```\n\n### Note conversion not working (viewing notes in browser)\n\nThe notelib service converts `.note` files to PNG for browser viewing. After conversion, notelib must upload the images back to supernote-service via HTTPS.\n\n**With self-signed certificates**, notelib cannot trust the certificate and uploads fail:\n```\ncurl_easy_perform() failed: SSL peer certificate or SSH remote key was not OK\n```\n\n**Solution - Create a CA bundle with your self-signed cert:**\n\nThe `docker-compose.example.yml` already includes the volume mount for this. You just need to create the CA bundle file:\n\n```bash\n# Start containers first (if not already running)\ndocker compose up -d\n\n# Extract the default CA bundle from notelib container and append your cert\ndocker exec supernote-notelib cat /etc/ssl/certs/ca-certificates.crt \u003e cert/ca-bundle.crt\ncat cert/server.crt \u003e\u003e cert/ca-bundle.crt\n\n# Restart to apply\ndocker compose down \u0026\u0026 docker compose up -d\n```\n\n**Check logs** to confirm the issue or verify the fix:\n```bash\ndocker logs supernote-notelib --tail 50 | grep -i \"SSL\\|certificate\\|upload\"\n```\n\n## Maintenance\n\n### Checking for Updates\n\nSupernote doesn't publish a compatibility matrix, so there's no official signal when to update. The safest approach:\n\n**1. Check Supernote's official docker-compose for version changes:**\n```bash\ncurl -s https://supernote-private-cloud.supernote.com/docker-deploy/docker-compose.yml\n```\n\nWhen Supernote bumps MariaDB or Redis versions in their official file, it's safe to update yours.\n\n**2. Check for new Supernote image versions on Docker Hub:**\n- [supernote/supernote-service](https://hub.docker.com/r/supernote/supernote-service/tags)\n- [supernote/notelib](https://hub.docker.com/r/supernote/notelib/tags)\n\n**3. Conservative approach:** MariaDB 10.6.x and Redis 7.x are LTS/stable branches. Only update these when Supernote's official compose changes, or if you need security patches.\n\n**4. Community resources:**\n- [Supernote subreddit](https://reddit.com/r/supernote) — users often report issues with new versions\n- [Supernote Support](https://support.supernote.com/) — official announcements\n\n### Applying Updates\n\n1. Update image versions in `docker-compose.yml`\n2. Pull and restart: `docker compose up -d`\n3. Docker will automatically pull new images\n\n### Rotate SSL Certificate\n\n1. Generate new certificate with CA extensions (see Generate SSL Certificate section)\n2. Copy to `cert/` directory\n3. Recreate CA bundle for notelib (see Note conversion troubleshooting section)\n4. Restart: `docker compose down \u0026\u0026 docker compose up -d`\n5. Re-install certificate on mobile devices if applicable\n\n## Security Considerations\n\n- **Self-signed HTTPS**: Protects data in transit on local network\n- **Database password**: Stored in `.env` (not committed to git)\n- **Redis password**: Password-protected; not exposed to network\n- **Private network**: Services isolated from other containers\n- **No public exposure**: Only accessible on local network by default\n\n## Files Overview\n\n```\n./\n├── docker-compose.yml          # Service definitions (from example)\n├── docker-compose.example.yml  # Example configuration\n├── .env                        # Environment variables (from example)\n├── .env.example                # Example environment\n├── supernotedb.sql             # Database schema\n├── supernote-email-init.sql.example  # Email config template\n├── cert/                       # SSL certificates\n├── data/                       # Persistent data\n├── logs/                       # Application logs\n└── README.md                   # This file\n```\n\n## License\n\nThis Docker configuration is provided as-is for self-hosting Supernote Private Cloud. Supernote and related services are trademarks of Ratta Software.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fliketheduck%2Fsupernote-private-cloud-docker","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fliketheduck%2Fsupernote-private-cloud-docker","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fliketheduck%2Fsupernote-private-cloud-docker/lists"}