Shaark Laravel Package

Getting Started

Shaark is a self-hosted Laravel application (bookmarks + notes + full-text search), not a Composer library you require — so "getting started" means standing up an instance, then extending it.

1. Clone the repo (or use the provided Docker setup) and copy .env.example to .env.
2. Set APP_URL, APP_KEY (php artisan key:generate), and your DB connection (SQLite is the low-friction default; MySQL/MariaDB for anything multi-user).
3. Run php artisan migrate and create your first account — as of 1.2.44 user creation and deletion from the admin UI actually work (see #77, #87), so you no longer need to hand-edit the DB or tinker to provision a second account.
4. Log in and add one link with a couple of tags, then immediately try the search box — that's the feedback loop you'll live in.

Where to look first in the codebase: routes/ (web + any API routes), app/Models/ (Link, Tag, Note), and the config directory for archive/search toggles. First real use case: replace a browser bookmark folder + a notes app with one searchable index, tagging entries by project so search + tag filter becomes your retrieval path.

Implementation Patterns

Capture workflow. The daily loop is: paste URL → title auto-fills → add tags → optionally toggle "archive" to keep a local copy of the page. Treat tags as your primary taxonomy (project, client, topic) and resist free-text-only; tags are what make the search results navigable months later.

Multi-user provisioning (new in 1.2.44). The create/delete user fixes unlock the small-team pattern: one admin provisions accounts per person rather than sharing credentials. Pattern:

• Provision via the admin users screen, then have each user set their own password.
• Keep an admin account separate from daily-use accounts so a mis-scoped delete doesn't take out your own data.
• Before any bulk delete, snapshot the DB and the archive storage directory — links, tags and archived pages are spread across both.

Sharing / read-only access. Use the public-link or guest-mode features for anything you want to hand to a colleague or client instead of granting an account. Pattern: keep internal/project tags private, and expose only curated entries as public links.

Integration tips.

• If you need programmatic capture (browser extension, RSS-to-Shaark, a Slack slash command), prefer hitting the app's HTTP endpoints over writing to the DB directly — the app owns tag de-duplication and search indexing.
• For anything the HTTP layer doesn't cover, drive the Eloquent models inside your own Artisan command (app/Console/Commands), and schedule it in Kernel.php. Model-level writes bypass index/archive side effects, so mirror whatever the controllers do.
• Front it with a reverse proxy (nginx/Traefik) and terminate TLS there; keep APP_URL in sync or generated public links will point at the wrong host.
• Run the queue worker if you enable archiving — page fetches shouldn't block the request cycle.

Ops pattern. Nightly: DB dump + archive directory tarball. Weekly: prune archived copies you never revisited. This is the single highest-value habit for a Shaark instance, because archive storage grows monotonically.

Gotchas and Tips

• Laravel 6.20 is end-of-life. 1.2.44 pins the framework at the last Laravel 6 patch. Laravel 6 stopped receiving security fixes in 2022, so treat this as a maintenance liability: run it behind auth/VPN, don't expose it naked to the internet, and budget an upgrade (Laravel 8/9) if you're keeping it. Verify the PHP version constraints before you upgrade your runtime — Laravel 6 caps you at PHP 7.4-ish.
• Default user email is [email protected] (changed in 1.2.44). Any account created without an explicit email now lands on that placeholder — which means password-reset and notification mail go nowhere, and a second such user may collide on a unique email index. Always fill in a real email at creation time; if the create form doesn't ask for one, set it right after via tinker or the edit screen.
• Deleting users is destructive and now one click away. Confirm what cascades: links, tags, notes and archived files owned by that user. Test the cascade on a throwaway account on a staging copy before you remove a real one — "delete worked" (#87) doesn't tell you whether orphans were cleaned up.
• Archive storage permissions are the most common silent failure: the web user needs write access to the storage path, and php artisan storage:link must have been run. Failed archives often fail quietly — check the Laravel log, not the UI.
• Search quality is DB-dependent. SQLite uses FTS tables; MySQL uses fulltext indexes with different tokenisation and minimum word length. If search "works on my machine" but not in prod, this is usually why — and reindexing after a DB migration is not automatic.
• Extension points, in order of safety: config toggles → Blade/Vue view overrides → model observers for side effects (e.g. notify on new link) → editing core controllers last. Because this is an application, not a package, your changes live in-tree; keep a git diff against upstream and rebase carefully on each release, or you'll lose the 1.2.44-style fixes.
• Upgrade routine for this repo: read the release notes for anything touching users/auth (1.2.44 does), back up DB + archives, pull, run php artisan migrate, clear caches (config:clear, view:clear), then smoke-test login, user create, user delete, and search on a non-production instance.