{"id":32595255,"url":"https://github.com/christancho/linkwarden-docker-compose","last_synced_at":"2026-05-13T12:46:14.579Z","repository":{"id":319904229,"uuid":"1080047060","full_name":"christancho/linkwarden-docker-compose","owner":"christancho","description":"Portainer-ready Docker Compose setup for Linkwarden with OpenAI integration.","archived":false,"fork":false,"pushed_at":"2025-10-20T19:54:34.000Z","size":10,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-10-20T21:32:07.477Z","etag":null,"topics":["docker-compose","linkwarden","openai","portainer"],"latest_commit_sha":null,"homepage":"","language":null,"has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/christancho.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","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-10-20T19:37:33.000Z","updated_at":"2025-10-20T19:58:30.000Z","dependencies_parsed_at":"2025-10-20T21:32:10.916Z","dependency_job_id":null,"html_url":"https://github.com/christancho/linkwarden-docker-compose","commit_stats":null,"previous_names":["christancho/linkwarden-docker-compose"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/christancho/linkwarden-docker-compose","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/christancho%2Flinkwarden-docker-compose","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/christancho%2Flinkwarden-docker-compose/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/christancho%2Flinkwarden-docker-compose/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/christancho%2Flinkwarden-docker-compose/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/christancho","download_url":"https://codeload.github.com/christancho/linkwarden-docker-compose/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/christancho%2Flinkwarden-docker-compose/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32983697,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-13T11:31:52.688Z","status":"ssl_error","status_checked_at":"2026-05-13T11:31:52.072Z","response_time":115,"last_error":"SSL_read: 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":["docker-compose","linkwarden","openai","portainer"],"created_at":"2025-10-30T03:34:57.268Z","updated_at":"2026-05-13T12:46:14.256Z","avatar_url":"https://github.com/christancho.png","language":null,"funding_links":[],"categories":[],"sub_categories":[],"readme":"# Linkwarden Docker Compose Setup\n\nA production-ready Docker Compose configuration for [Linkwarden](https://linkwarden.app/) - a self-hosted bookmark manager with AI-powered tagging capabilities.\n\n## Features\n\n- **Portainer Compatible** - Optimized for deployment via Portainer stacks\n- **OpenAI Integration** - Built-in AI tagging using OpenAI's GPT models\n- **PostgreSQL 16** - Reliable database backend with persistent storage\n- **Environment-based Configuration** - All secrets managed via `.env` file\n- **Security Hardened** - No hardcoded credentials, proper network isolation\n\n## What is Linkwarden?\n\nLinkwarden is a self-hosted, open-source collaborative bookmark manager to collect, organize and archive webpages. It supports tagging, categorization, and AI-powered content analysis.\n\n## Prerequisites\n\n- Docker and Docker Compose installed\n- OpenAI API key (optional, for AI tagging feature)\n- Minimum 2GB RAM recommended\n- Portainer (optional, but recommended for easy management)\n\n## Quick Start\n\n### 1. Clone the Repository\n\n```bash\ngit clone https://github.com/christancho/linkwarden-docker-compose.git\ncd linkwarden-docker-compose\n```\n\n### 2. Configure Environment Variables\n\nCopy the example environment file and edit it:\n\n```bash\ncp .env.example .env\nnano .env\n```\n\nUpdate the following required variables in `.env`:\n\n```bash\n# PostgreSQL Configuration\nPOSTGRES_PASSWORD=your_secure_postgres_password\n\n# Linkwarden Configuration\nNEXTAUTH_SECRET=your_secure_nextauth_secret  # Generate with: openssl rand -base64 32\nNEXTAUTH_URL=http://localhost:4000/api/v1/auth\n\n# Data Directory\nLINK_DIR=/path/to/your/linkwarden/data  # Absolute path where data will be stored\n\n# OpenAI Configuration (Optional - for AI tagging)\nOPENAI_API_KEY=sk-your-openai-api-key-here\nOPENAI_MODEL=gpt-4o\n```\n\n### 3. Generate Secure Secrets\n\n```bash\n# Generate NEXTAUTH_SECRET\nopenssl rand -base64 32\n```\n\n### 4. Deploy\n\n#### Option A: Using Docker Compose (Command Line)\n\n```bash\ndocker-compose up -d\n```\n\n#### Option B: Using Portainer (Recommended)\n\n1. Log in to your Portainer instance\n2. Navigate to **Stacks** \u003e **Add Stack**\n3. Name your stack (e.g., `linkwarden`)\n4. Choose **Git Repository** or **Upload** method:\n   - **Git Repository**: Paste this repository URL\n   - **Upload**: Copy contents of `docker-compose.yml`\n5. Add environment variables from your `.env` file in the **Environment variables** section\n6. Click **Deploy the stack**\n\n### 5. Access Linkwarden\n\nOpen your browser and navigate to:\n\n```\nhttp://localhost:4000\n```\n\nOr replace `localhost` with your server's IP address.\n\n## OpenAI Integration\n\nThis setup includes OpenAI integration for AI-powered bookmark tagging. The AI can automatically:\n\n- Analyze bookmark content\n- Generate relevant tags and keywords\n- Improve searchability and organization\n\n### Configuration\n\nTo enable AI tagging:\n\n1. Get an OpenAI API key from [https://platform.openai.com/api-keys](https://platform.openai.com/api-keys)\n2. Add it to your `.env` file:\n   ```bash\n   OPENAI_API_KEY=sk-proj-your-actual-key-here\n   OPENAI_MODEL=gpt-4o\n   ```\n3. Restart the container:\n   ```bash\n   docker-compose restart linkwarden\n   # OR via Portainer: Select stack \u003e Restart\n   ```\n\n### Model Options\n\n- `gpt-4o` - Most capable, higher cost\n- `gpt-4o-mini` - Balanced performance and cost\n- `gpt-3.5-turbo` - Fastest, lowest cost\n\n### Custom OpenAI Providers\n\nIf using an OpenAI-compatible provider (not official OpenAI), add:\n\n```bash\nCUSTOM_OPENAI_BASE_URL=https://your-custom-endpoint.com\n```\n\n## Configuration\n\n### Environment Variables\n\n| Variable | Description | Required | Default |\n|----------|-------------|----------|---------|\n| `POSTGRES_PASSWORD` | PostgreSQL database password | Yes | - |\n| `NEXTAUTH_SECRET` | Secret for authentication sessions | Yes | - |\n| `NEXTAUTH_URL` | Authentication callback URL | Yes | `http://localhost:4000/api/v1/auth` |\n| `LINK_DIR` | Directory for persistent data storage | Yes | - |\n| `OPENAI_API_KEY` | OpenAI API key for AI tagging | No | - |\n| `OPENAI_MODEL` | OpenAI model to use | No | `gpt-4o` |\n| `CUSTOM_OPENAI_BASE_URL` | Custom OpenAI-compatible endpoint | No | OpenAI's API |\n\n### Ports\n\n- **4000** - Linkwarden web interface (mapped from container port 3000)\n- **5432** - PostgreSQL (internal network only)\n\n### Data Persistence\n\nData is persisted in the directory specified by `LINK_DIR`:\n\n- `${LINK_DIR}/pgdata` - PostgreSQL database files\n- `${LINK_DIR}/data` - Linkwarden application data\n\n## Portainer Deployment Tips\n\n1. **Stack Environment Variables**: When deploying via Portainer, add each environment variable individually in the stack configuration UI\n2. **Volume Paths**: Ensure `LINK_DIR` points to a directory accessible by the Portainer agent\n3. **Updates**: To update Linkwarden, pull the latest image via Portainer's **Recreate** function\n4. **Logs**: Monitor container logs directly in Portainer's **Logs** tab\n\n## Updating\n\n### Via Docker Compose\n\n```bash\ndocker-compose pull\ndocker-compose up -d\n```\n\n### Via Portainer\n\n1. Navigate to your stack\n2. Click **Update the stack**\n3. Enable **Re-pull image and redeploy**\n4. Click **Update**\n\n## Backup\n\nIt's recommended to regularly backup your data directory:\n\n```bash\n# Backup PostgreSQL data and Linkwarden files\ntar -czf linkwarden-backup-$(date +%Y%m%d).tar.gz ${LINK_DIR}/\n```\n\n## Troubleshooting\n\n### Container won't start\n\n1. Check logs: `docker-compose logs linkwarden`\n2. Verify all required environment variables are set\n3. Ensure `LINK_DIR` exists and has proper permissions\n\n### OpenAI features not working\n\n1. Verify `OPENAI_API_KEY` is correctly set\n2. Check API key has sufficient credits at [https://platform.openai.com/usage](https://platform.openai.com/usage)\n3. Review container logs for API errors\n\n### Can't access Linkwarden\n\n1. Verify port 4000 is not in use: `lsof -i :4000`\n2. Check firewall settings\n3. Ensure `NEXTAUTH_URL` matches your access URL\n\n## Security Considerations\n\n- Never commit `.env` file to version control\n- Use strong passwords for `POSTGRES_PASSWORD`\n- Regenerate `NEXTAUTH_SECRET` regularly\n- Consider using a reverse proxy (Nginx, Traefik) with SSL in production\n- Restrict OpenAI API key permissions if possible\n- Monitor OpenAI API usage to prevent unexpected costs\n\n## Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n\n## License\n\nThis Docker Compose configuration is licensed under the Apache License 2.0. See [LICENSE](LICENSE) for details.\n\nLinkwarden itself is licensed under the [AGPLv3 License](https://github.com/linkwarden/linkwarden/blob/main/LICENSE).\n\n## Resources\n\n- [Linkwarden Official Website](https://linkwarden.app/)\n- [Linkwarden GitHub Repository](https://github.com/linkwarden/linkwarden)\n- [Linkwarden Documentation](https://docs.linkwarden.app/)\n- [Portainer Documentation](https://docs.portainer.io/)\n- [OpenAI Platform](https://platform.openai.com/)\n\n## Support\n\nFor issues related to:\n- **This Docker setup**: Open an issue in this repository\n- **Linkwarden application**: Visit [Linkwarden's GitHub](https://github.com/linkwarden/linkwarden/issues)\n- **OpenAI API**: Check [OpenAI's documentation](https://platform.openai.com/docs)","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchristancho%2Flinkwarden-docker-compose","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fchristancho%2Flinkwarden-docker-compose","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchristancho%2Flinkwarden-docker-compose/lists"}