toolz/linkding
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: database

Browse Source
This commit is contained in:
0x1d
2025-11-16 10:33:59 +01:00
parent 3cf9601a71
commit 1417023395
14 changed files with 1436 additions and 192 deletions
Download Patch File Download Diff File Expand all files Collapse all files

167
README.md
View File

@@ -7,22 +7,29 @@ LinkDing is a minimal bookmarking application where you can paste links and get
- Paste links and get a list of links with title, description, and image
- Automatic metadata extraction
- Search functionality by title, description, and URL
- Organize links into custom lists
- Archive/unarchive links
- Public and private lists
- Modern, responsive web interface
- Support for JavaScript-heavy sites using Puppeteer
- Automatic fallback from HTTP scraping to browser rendering
- LDAP authentication support
- PostgreSQL database with automatic migrations
## Tech Stack
- **Backend**: Express.js (Node.js)
- **Frontend**: Vanilla JavaScript, HTML5, CSS3
- **Web Scraping**: Cheerio + Puppeteer (for JavaScript-heavy sites)
- **Data Storage**: JSON file
- **Database**: PostgreSQL with Sequelize ORM
- **Authentication**: LDAP (optional)
## Installation
### Prerequisites
- Node.js 18+ (or Docker)
- PostgreSQL 12+ (or Docker)
- Chromium/Chrome (for Puppeteer support, optional)
### Local Installation
@@ -37,49 +44,86 @@ LinkDing is a minimal bookmarking application where you can paste links and get
npm install
```
3. Start the server:
3. Set up environment variables:
```bash
cp .env.example .env
# Edit .env with your database configuration
```
4. Start PostgreSQL database and the application:
```bash
make dev
```
Or manually:
```bash
# Start PostgreSQL (using docker-compose)
docker compose -f docker-compose.dev.yaml up -d
# Start the application
npm start
```
4. Open your browser to `http://localhost:3000`
5. Open your browser to `http://localhost:3000`
**Note**: On first startup, the application will:
- Create database tables automatically
- Migrate any existing JSON files (`data/links.json` and `data/lists.json`) to the database
- Rename migrated JSON files to `*.json.bak`
### Docker Installation
1. Build the Docker image:
1. Set up environment variables:
```bash
docker build -t linkding .
cp .env.example .env
# Edit .env with your database configuration (or use defaults)
```
2. Run the container:
```bash
docker run -d \
--name linkding \
-p 3000:3000 \
-v $(pwd)/data:/app/data \
linkding
```
Or use Docker Compose:
2. Use Docker Compose (recommended):
```bash
docker-compose up -d
```
This will start both PostgreSQL and the LinkDing application.
3. Access the application at `http://localhost:3000`
**Note**: The Docker Compose setup includes:
- PostgreSQL database with persistent volume
- LinkDing application container
- Automatic database initialization and migrations
## Usage
1. **Add a Link**: Paste a URL into the input field and click "Add Link"
2. **Search**: Use the search bar to filter links by title, description, or URL
3. **View Links**: Browse your saved links with images, titles, and descriptions
4. **Delete Links**: Click the "Delete" button on any link card to remove it
4. **Organize Links**: Create lists and assign links to them
5. **Archive Links**: Archive links to hide them from the main view
6. **Public Lists**: Make lists public to share them with unauthenticated users
7. **Delete Links**: Click the "Delete" button on any link card to remove it
## API Endpoints
- `GET /api/links` - Get all saved links
### Links
- `GET /api/links` - Get all saved links (authenticated users see all, unauthenticated see only public lists)
- `GET /api/links/search?q=query` - Search links
- `POST /api/links` - Add a new link (body: `{ "url": "https://example.com" }`)
- `DELETE /api/links/:id` - Delete a link by ID
- `POST /api/links` - Add a new link (body: `{ "url": "https://example.com" }`) - Requires authentication
- `PATCH /api/links/:id/archive` - Archive/unarchive a link (body: `{ "archived": true }`) - Requires authentication
- `PATCH /api/links/:id/lists` - Update link's lists (body: `{ "listIds": ["uuid1", "uuid2"] }`) - Requires authentication
- `DELETE /api/links/:id` - Delete a link by ID - Requires authentication
### Lists
- `GET /api/lists` - Get all lists (authenticated users see all, unauthenticated see only public)
- `POST /api/lists` - Create a new list (body: `{ "name": "List Name" }`) - Requires authentication
- `PUT /api/lists/:id` - Update a list (body: `{ "name": "New Name" }`) - Requires authentication
- `PATCH /api/lists/:id/public` - Toggle list public status (body: `{ "public": true }`) - Requires authentication
- `DELETE /api/lists/:id` - Delete a list by ID - Requires authentication
### Authentication
- `GET /api/auth/status` - Check authentication status
- `POST /api/auth/login` - Login with LDAP credentials (body: `{ "username": "user", "password": "pass" }`)
- `POST /api/auth/logout` - Logout
## Metadata Extraction
@@ -100,13 +144,63 @@ The application automatically extracts:
## Environment Variables
See `.env.example` for a complete list of environment variables. Key variables include:
### Application
- `PORT` - Server port (default: 3000)
- `CHROME_EXECUTABLE_PATH` - Path to Chrome/Chromium executable (for Puppeteer)
- `NODE_ENV` - Environment mode (production/development)
## Data Storage
### Database
- `DATABASE_URL` - Full PostgreSQL connection string (e.g., `postgresql://user:password@host:port/database`)
- `DATABASE_SSL` - Enable SSL for database connection (true/false)
- `DB_HOST` - Database host (default: localhost)
- `DB_PORT` - Database port (default: 5432)
- `DB_NAME` - Database name (default: linkding)
- `DB_USER` - Database user (default: postgres)
- `DB_PASSWORD` - Database password (default: postgres)
Links are stored in `data/links.json`. Make sure this directory exists and is writable. When using Docker, mount the `data` directory as a volume for persistence.
### Session & Cookies
- `SESSION_SECRET` - Secret key for session encryption (change in production!)
- `SESSION_NAME` - Session cookie name (default: connect.sid)
- `COOKIE_SECURE` - Use secure cookies (default: true in production)
- `COOKIE_SAMESITE` - Cookie SameSite attribute (default: none for secure, lax otherwise)
- `COOKIE_DOMAIN` - Cookie domain (optional)
- `COOKIE_PATH` - Cookie path (default: /)
- `TRUST_PROXY` - Trust proxy headers (default: true)
### LDAP Authentication
- `LDAP_ADDRESS` - LDAP server address
- `LDAP_BASE_DN` - LDAP base distinguished name
- `LDAP_USER` - LDAP bind user
- `LDAP_PASSWORD` - LDAP bind password
- `LDAP_USERS_FILTER` - LDAP user search filter
- And more... (see `.env.example`)
### Puppeteer
- `CHROME_EXECUTABLE_PATH` - Path to Chrome/Chromium executable (for Puppeteer)
## Database
LinkDing uses PostgreSQL for data storage. The application automatically:
- **Creates tables** on first startup
- **Runs migrations** to keep the schema up to date
- **Migrates JSON files** if `data/links.json` or `data/lists.json` exist, then renames them to `*.json.bak`
### Migration System
The application includes a migration system for database schema changes:
- Migrations are stored in `migrations/` directory
- Migrations are automatically run on startup
- Each migration is tracked in the `SequelizeMeta` table
### Data Migration
If you have existing JSON files:
1. Place `links.json` and `lists.json` in the `data/` directory
2. Start the application
3. The files will be automatically migrated to PostgreSQL
4. Original files will be renamed to `links.json.bak` and `lists.json.bak`
## Troubleshooting
@@ -127,10 +221,31 @@ Some sites block automated requests. The app automatically:
## Development
### Using Make (Recommended)
```bash
# Start PostgreSQL and the application
make dev
# Start only PostgreSQL
make up
# Stop PostgreSQL
make down
# Stop and remove volumes (clean slate)
make clean
```
### Manual Development Setup
```bash
# Install dependencies
npm install
# Start PostgreSQL (using docker-compose)
docker compose -f docker-compose.dev.yaml up -d
# Run in development mode with auto-reload
npm run dev
@@ -138,6 +253,14 @@ npm run dev
npm start
```
### Database Management
The application uses Sequelize ORM with PostgreSQL. Database migrations are automatically run on startup. To manually manage the database:
- Connect to PostgreSQL: `psql -h localhost -U postgres -d linkding`
- Check migrations: Query the `SequelizeMeta` table
- View tables: `\dt` in psql
## License
ISC