# Project pack: wallabag @ 72bdffa

Facts about **wallabag** for an AI following the [BespokeAI handover guide](https://handoff.bespokeai.software/guide/v2.md). This pack is pinned to one version and never changes after publication.

> wallabag is a read-it-later service you run yourself. Save any web page with one click from your browser or phone, and wallabag keeps a clean copy of the text and pictures with no adverts or pop-ups. Read it later on any device, even offline in the apps, add highlights and notes, and tag articles automatically. You can bring your saved articles from Pocket, Instapaper and others.

## Version and source
- Repository: https://github.com/wallabag/wallabag
- Pinned commit: `72bdffa41fd6b73a547e140206cf702e7bd29f8f`. Use exactly this version.
- Fresh checkout: use the setup below in an empty folder. If you already have this exact source checked out, keep your branch and use the development command instead; do not clone again or reset local changes.
- Or download a zip: https://github.com/wallabag/wallabag/archive/72bdffa41fd6b73a547e140206cf702e7bd29f8f.zip
- Official docs: https://doc.wallabag.org
- Licence: **MIT**. Very permissive. You can use, change and share it, even commercially. If you pass on copies, keep the copyright notice and licence text.

## Running the pinned source
- Fresh pinned-source setup (skip clone and checkout in an existing worktree):

  ```sh
  git clone https://github.com/wallabag/wallabag bespoke-wallabag
  cd bespoke-wallabag
  git checkout --detach 72bdffa41fd6b73a547e140206cf702e7bd29f8f
  # Prepare development requirements and local configuration first.
  # Setup notes: http://127.0.0.1:8000; run make dev-watch for assets
  cp docker/php/env.example docker/php/env && make dev-docker-up && make dev-setup
  ```

The commands below are a starting point from the reviewed source. Prepare the listed tools, local configuration and companion services before starting the app. These instructions have not yet been validated in participant sessions.

### Separate trial of the current release
This tries an upstream release, which may differ from the pinned source above. It does not run your source changes. Use only sample data and a separate data directory or volume. Check the upstream documentation before running it.

  ```sh
  docker run -d --name wallabag -p 8080:80 -v wallabag-data:/var/www/wallabag/data -v wallabag-images:/var/www/wallabag/web/assets/images -e APP_SECRET=$(openssl rand -hex 16) -e WALLABAG_BASE_URL=http://localhost:8080 -e DATABASE_URL=sqlite:////var/www/wallabag/data/db/wallabag.sqlite wallabag/wallabag
  # open http://localhost:8080 and log in as wallabag / wallabag, then change the password.
  # This follows the install docs at the pinned commit; older image releases may use different variable names (see Docker Hub).
  ```

- Needs: Docker, or PHP 8.2+ with Composer, a web server and SQLite, PostgreSQL or MySQL, For development, GNU make, Node.js and Yarn (or the Docker dev stack)
- Develop: `cp docker/php/env.example docker/php/env && make dev-docker-up && make dev-setup   # http://127.0.0.1:8000; run make dev-watch for assets`
- Test: `make test`
- Check/lint: `make lint`
- Build: `make build`
- Stack: php, javascript, twig, scss (Symfony 5.4, Doctrine, Twig, Webpack Encore, Stimulus, Materialize CSS, Graby). Difficulty for a non-developer with an AI: **moderate**. A long-lived Symfony app with good structure: controllers in src/Controller/, pages in templates/ (Twig), styles in assets/scss/ and small Stimulus controllers in assets/controllers/. Tagging rules, custom CSS and the API cover a lot without code. Code changes need PHP 8.2+ and Node for the assets; the Docker dev stack makes that easier.

## The project's own AI instructions
Read these in the repository before changing code: `.github/CONTRIBUTING.md`.

## Customisation points (settings → extend → code)
- **user-settings** [settings]: Items per page, your reading speed (for "x min" estimates), where to go after archiving, thumbnails and language. Light, dark or automatic theme is in the side menu. → `Config → Settings (doc/content/user/configuration/settings.md)`
- **article-display** [settings]: Make the reading page comfortable for you without any code. → `Config → Article display (font family, font size, line height, maximal width)`
- **tagging-rules** [settings]: Tag articles automatically, e.g. "readingTime <= 3" → "quick read", or anything from bbc.co.uk → "news". → `Config → Tagging rules (doc/content/user/configuration/tagging_rules.md)`
- **feeds** [settings]: Private Atom feeds of unread, starred or tagged articles for a feed reader or e-reader. → `Config → Feeds (doc/content/user/configuration/rss.md)`
- **instance-settings** [settings]: Sharing buttons, public links for articles, paywall logins, sign-ups and the instance name. → `Internal settings (admin) and environment variables in .env (doc/content/admin/internal_settings.md, parameters.md)`
- **custom-css** [extend]: Instance-wide styles loaded on every page, such as a reading font or larger text. No rebuild. → `web/custom.css (doc/content/admin/custom_css.md)`
- **api-and-apps** [extend]: Save from scripts, shortcuts or other apps, and read on Android or iOS. → `REST API with OAuth clients (src/Controller/Api/, doc/content/developer/api/); browser extension and phone apps`
- **importers** [extend]: Bring in years of saved articles from another service. → `Import page (src/Import/, src/Controller/Import/) for Pocket, Instapaper, Pinboard, Omnivore, browser bookmarks…`
- **templates-and-styles** [code]: Change how lists and the reading page look and behave. → `templates/ (e.g. templates/Entry/entry.html.twig for the reading view), assets/scss/, assets/controllers/`
- **backend** [code]: New features or data, such as a reading streak or a 'read aloud' button. → `src/Controller/, src/Entity/ + Doctrine migrations in migrations/, text in translations/messages.en.yml`

## Must keep working
- Saved articles, tags and highlights. Back up the database and images before upgrades or code changes.
- The REST API and OAuth, which the browser extension and phone apps rely on.
- Each user only sees their own articles; public share links only for articles the user chose to share.
- Database changes need a Doctrine migration in migrations/.

## Staying updatable
Tagging rules, feeds, internal settings, custom.css and the API cover most personal tweaks without a fork. Upstream accepts pull requests against master that pass `make test` and the linters (see .github/CONTRIBUTING.md). The project name is always written in lower case: wallabag.

## Data, costs and safety
- Personal data: **yes**. Stored in: Database (SQLite file in data/db/ by default, or PostgreSQL/MySQL) for articles, tags and highlights; saved pictures in web/assets/images. What you read says a lot about you. Back up the database and the images folder (see doc/content/admin/backup.md). You can also export everything as JSON, CSV or ePUB from the app.
- Service: Email (any provider via MAILER_DSN) (optional, free with most providers): Account confirmation, password resets and two-factor codes by email.
- Service: Redis or RabbitMQ (optional, free (self-hosted)): Run big imports (thousands of articles) in the background.
- Service: The websites you save (required, free): wallabag downloads each saved page from its website. Paywalled sites can use your own login (site credentials).
- Setting `APP_SECRET` (**secret**: the person enters it themselves, never in chat): Random secret for sessions and security tokens. The example value in .env must be replaced.
- Setting `WALLABAG_BASE_URL`: The full address you open wallabag at, e.g. https://read.example.com.
- Setting `DATABASE_URL` (**secret**: the person enters it themselves, never in chat): Database address. SQLite by default; can contain a password for PostgreSQL or MySQL.
- Setting `WALLABAG_REGISTRATION_ENABLED`: 1 lets anyone create an account; keep 0 for a private instance.
- Setting `WALLABAG_SERVER_NAME`: The name of your instance shown to users.
- Setting `DEFAULT_LOCALE`: Default interface language, e.g. en or fr.
- Setting `MAILER_DSN` (**secret**: the person enters it themselves, never in chat): Email server address for confirmations and resets. Often includes a password.
- Setting `WALLABAG_FROM_EMAIL`: The sender address on wallabag's emails.
- Setting `REDIS_URL`: Redis address for background imports.
- Change the default wallabag / wallabag login and set a random APP_SECRET straight away.
- Keep WALLABAG_REGISTRATION_ENABLED=0 on an internet-facing server, and use HTTPS.
- Shared article links are public to anyone who has them.
- Site credentials for paywalled sites are stored on your server. Only add them if you trust where it runs.

---

# Customising wallabag

wallabag is a well-organised Symfony app. **Most personal tweaks are settings, tagging rules or a little custom CSS.** Use levels 1 and 2 first.

## Level 1: Settings (no code)
- **Your settings:** Config → Settings.
  - Items per page and reading speed (wallabag recalculates "x min" for every article).
  - What happens after you archive or delete, thumbnails and interface language.
- **Reading page:** Config → *Article display*. Font family, font size, line height and maximal width.
- **Theme:** light, dark or automatic, from the side menu.
- **Automatic tags:** Config → *Tagging rules*.
  - Examples: `readingTime <= 3` → `quick read`; `domainName = "bbc.co.uk"` → `news`.
  - See `doc/content/user/configuration/tagging_rules.md`.
- **Ignore origin rules:** Config → *Ignore origin rules*, so redirect links (newsletters, link shorteners) are saved under the real site.
- **Feeds:** Config → *Feeds*. Create a token for private Atom feeds of unread, starred, archived or tagged articles.
- **Instance (admin):**
  - *Internal settings* control sharing buttons, public article links, paywall logins and analytics (`doc/content/admin/internal_settings.md`).
  - Environment variables in `.env` control sign-ups, the instance name, email and the database (`doc/content/admin/parameters.md`).

## Level 2: Extend (no fork)
- **Custom CSS:** create `web/custom.css`. It is loaded on every page for all users (`doc/content/admin/custom_css.md`).
- **Apps:** browser extension (wallabagger), Android and iOS apps. Create an API client under *API clients management* (`doc/content/apps/`).
- **REST API** with OAuth (`doc/content/developer/api/`). Save, tag, archive or export from scripts and shortcuts.
- **Imports:** Pocket, Instapaper, Pinboard, Omnivore, Readability, Shaarli, Delicious, browser bookmarks and other wallabag servers. Use Redis or RabbitMQ for very big imports (`doc/content/admin/asynchronous.md`).
- **Exports:** ePUB, PDF, JSON, CSV and XML for one article or a whole list.

## Level 3: Code
Read upstream `.github/CONTRIBUTING.md` first.

| Change | Where |
|---|---|
| Reading page | `templates/Entry/entry.html.twig`, styles in `assets/scss/_article.scss` |
| Article lists and cards | `templates/Entry/entries.html.twig`, `templates/Entry/_card_*.html.twig`, `assets/scss/_cards.scss` |
| Dark theme | `assets/scss/_dark_theme.scss` |
| Browser behaviour | `assets/controllers/` (Stimulus) |
| Pages and actions | `src/Controller/` (e.g. `EntryController.php`, `ConfigController.php`) |
| API | `src/Controller/Api/` |
| New data | `src/Entity/` + a Doctrine migration in `migrations/` |
| New importer | `src/Import/` + `src/Controller/Import/` |
| Text | `translations/messages.en.yml` (other languages via Weblate) |

## Running locally
- **Just use it:**
  1. Run `docker run -p 8080:80 -e APP_SECRET=… -e WALLABAG_BASE_URL=http://localhost:8080 -e DATABASE_URL=sqlite:////var/www/wallabag/data/db/wallabag.sqlite -v wallabag-data:/var/www/wallabag/data -v wallabag-images:/var/www/wallabag/web/assets/images wallabag/wallabag`
  2. Log in as wallabag / wallabag and change the password.
  3. Check Docker Hub for the variable names your image version expects.
- **Develop (Docker):**
  1. `cp docker/php/env.example docker/php/env`
  2. `make dev-docker-up`, then `make dev-setup`
  3. Open http://127.0.0.1:8000.
  4. Run `make dev-watch` in another terminal for CSS and JavaScript.
- **Develop (own PHP 8.2+):** `make dev`, then `make run` later.
- **Check:** `make test` (unit, integration, functional) and `make lint` (PHP-CS-Fixer, PHPStan, TwigCS, ESLint, Stylelint, translations).

## Pitfalls
- Back up the database and `web/assets/images` before upgrades or code changes.
- Front-end changes need a rebuild (`make build` or `make dev-watch`). Editing files in `web/build/` directly gets overwritten.
- Phone apps and the browser extension use the API. Don't change existing API responses.
- Some sites block or change their pages. Fetching problems are usually site-config issues (`doc/content/user/errors_during_fetching.md`), not wallabag bugs.

---
Machine-readable: [bespoke.yaml](https://handoff.bespokeai.software/p/wallabag/72bdffa/r2/bespoke.yaml) · Hosting options: [hosting.md](https://handoff.bespokeai.software/p/wallabag/72bdffa/r2/hosting.md) · Agent skill: [SKILL.md](https://handoff.bespokeai.software/p/wallabag/72bdffa/r2/SKILL.md)