Skip to content

About

A small web app that can be used to provide restricted access to corporate media via providers like Vimeo or Youtube

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

15 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Media Access Manager

Hand out time- and usage-limited access to hosted media – as links or printed QR codes – without giving anyone the media itself.

An admin picks videos from a media provider (Vimeo today), optionally bundles them into groups, and generates access tokens: single ones, or batches of hundreds exported as a QR code ZIP or PDF ready for print. A visitor opens https://your-host/{token}, and as long as the token's date window is open and its views are not used up, the media plays as an embed. Nothing is downloadable, no account is needed, and no visitor is tracked.

The whole UI is white-labelable through environment variables – logo, company name, colors, roundness – so a deployment can carry a customer's corporate design without a rebuild.

Note

Built with AI support. Large parts of this project – code, tests and documentation – were written with the help of AI coding assistants (see AGENTS.md for the guidelines they follow) and reviewed by humans before merging. Treat it accordingly: read the code before you run it in production, and please report anything that looks off.

Features

  • Token-based access – every token carries an optional start date, end date and view limit; an invalid token shows a friendly notice instead of the media
  • Media groups – one token (and one printed QR code) can hand out a whole set of media, with the view limit counted per media rather than once for the entire group
  • Batch generation – create many tokens at once and download their QR codes as a ZIP of images or a print-ready PDF
  • Provider abstraction – media sources implement a small interface and return oEmbed responses; Vimeo ships with the app, further providers plug in
  • Playback pre-flight check – the admin UI verifies whether a token holder could actually watch a media (privacy settings, domain whitelists) and shows a provider-specific checklist when it could not
  • White-label theming – brand color, logo, favicon, title, radius and density from environment variables, see docs/theming.md
  • View history and statistics – every spent view is recorded with its token, media and time: a per-token history answers "where did my views go?", and a statistics page shows views per day, per media and the latest ones
  • Single admin password – no user accounts, no user management
  • Localized – English and German, all strings via i18n keys
  • No tracking – no device identifiers, no IP addresses, no visitor accounts; the view history records only which token opened which media when

How it works

Admin

  1. Log in with the global admin password.
  2. Add media – the app lists what is available at the provider – and optionally arrange media into groups.
  3. Create a token or a batch of tokens for a media or a group, with a date window and/or a view limit.
  4. Download the QR codes and print, mail or hand them out.

Visitor

  • Single-media token: opening /{token} validates it, spends one view (recorded in the token's history) and renders the player.
  • Group token: /{token} lists the group's media with each entry's remaining views – browsing costs nothing. Picking one opens /{token}/{mediaId}, which spends a view on that media alone. Media that are used up stay visible, marked as such, so the visitor sees what they had and can ask for more.
  • If access has ended, the page explains why and – when NUXT_PUBLIC_SUPPORT_EMAIL is configured – offers a mail link to request a new one.

For the full picture of the data model and the flows, read docs/concept.md.

Tech stack

Nuxt 4 (SPA, ssr: false) with Nuxt UI and Tailwind CSS, Drizzle ORM on SQLite (better-sqlite3), nuxt-auth-utils for the admin session, @nuxtjs/i18n for translations, Vitest for unit tests and Playwright for end-to-end tests. Package manager is pnpm, Node 26+.

Getting started

nvm use 26
pnpm install
cp .env.example .env   # then edit it, see Configuration
pnpm dev

The app runs at http://localhost:3000. Log in at /auth/login with the password from NUXT_ADMIN_PASSWORD.

The SQLite database is created at data/mam.db on first use and migrations are applied automatically when the server first touches it – no manual setup step.

Configuration

All settings are environment variables (Nuxt runtimeConfig). Copy .env.example as a starting point.

Variable Required Description
NUXT_ADMIN_PASSWORD in production The single password protecting the admin UI. pnpm dev falls back to password.
NUXT_SESSION_PASSWORD in production Secret sealing the admin session cookie, at least 32 characters.
NUXT_VIMEO_API_TOKEN for Vimeo Vimeo API token used to list your videos and check their privacy settings.
NUXT_PUBLIC_SUPPORT_EMAIL no Address offered to visitors whose access has ended. Empty means no mail link.
NUXT_PUBLIC_THEME_* no White-label theme, see docs/theming.md.
NUXT_BRANDING_DIR no Where the files named by NUXT_PUBLIC_THEME_LOGO/_LOGO_DARK/_FAVICON are read from, defaults to branding (/app/branding).
NUXT_PUBLIC_PUBLISHER_* no Name and URL of whoever publishes the media, linked in header and footer.
NUXT_PUBLIC_POWERED_BY_* no Name and URL credited in the footer, defaults to the upstream project.
PORT no Port to listen on, defaults to 3000.

Important

NUXT_ADMIN_PASSWORD and NUXT_SESSION_PASSWORD only have defaults in development (the $development block in nuxt.config.ts), so no published image carries a password someone else knows. A production deployment must set both – until it does, the app refuses every login.

Set values in .env or leave the line out entirely: an empty value counts as a value and overrides the development default, which is why both are commented out in .env.example.

Tip

Quote hex colors in .env files – an unquoted # starts a comment there, so NUXT_PUBLIC_THEME_COLORS_PRIMARY=#0f4c81 arrives empty.

Vimeo setup

Without an API token the app still plays media through public oEmbed, but it cannot list your library or diagnose playback problems. Create a token with read access to your videos at developer.vimeo.com. For videos restricted to specific domains, add the host this app is served from to the whitelist – the accessibility check in the admin UI tells you exactly what is missing.

Deployment

Container images are published to the GitHub Container Registry on every push to main (tag next) and for every git tag:

docker run -d \
  -p 3000:3000 \
  -v mam-data:/app/data \
  -v ./logo.svg:/app/branding/logo.svg \
  -e NUXT_ADMIN_PASSWORD=... \
  -e NUXT_SESSION_PASSWORD=... \
  -e NUXT_VIMEO_API_TOKEN=... \
  -e NUXT_PUBLIC_THEME_LOGO=/branding/logo.svg \
  ghcr.io/geprog/media-access-manager:next

/app/data holds the SQLite database and is the only writable path – mount a volume there or the data is gone with the container.

/app/branding is empty and optional. It holds the logo and favicon of a white-label deployment, served at /branding/* and read on every request, which is what lets a published image be branded without a rebuild – mount the file and name it through NUXT_PUBLIC_THEME_LOGO/_FAVICON. Only the files those settings name are served; anything else in the directory answers 404. Do not mount into /app/public instead: that directory is frozen into a manifest at build time, and a file added there later is answered with the app's HTML rather than the image. See docs/theming.md.

To build it yourself:

pnpm build            # produces .output/
docker build -t media-access-manager .

Scripts

Command What it does
pnpm dev Development server with hot reload
pnpm build Production build into .output/
pnpm preview Serve the production build locally
pnpm lint ESLint (--fix to apply fixes)
pnpm typecheck vue-tsc over the whole project
pnpm spelling cspell over all files
pnpm test Vitest unit tests (pnpm test run for CI)
pnpm test:e2e Playwright end-to-end tests
pnpm playwright:install Install Playwright browsers and dependencies
pnpm db:generate Generate a migration from schema changes
pnpm db:migrate Apply migrations manually

Testing

Unit tests live next to the code they cover (*.test.ts) and focus on the logic: token validation, access windows, theme derivation, accessibility diagnosis. End-to-end tests in e2e/tests/ drive the real app with Playwright and never call external providers – provider responses are mocked. The suite runs on a single worker because every spec shares one server and one database, cleaning up after itself by name.

CI runs lint, typecheck, spelling, unit tests and E2E tests on every pull request.

Project structure

components/        Vue components (admin tables/forms, public player)
composables/       Shared reactive helpers
docs/              concept.md (architecture & data model), theming.md
e2e/               Playwright specs and helpers
i18n/locales/      en.json, de.json
pages/             Admin pages plus the public /{token} routes
plugins/           Theme injection
server/api/        REST endpoints (auth, media, groups, tokens, batches, access)
server/db/         Drizzle schema and migrations
server/services/   Auth, media, groups, tokens, QR, providers/
server/utils/      Validation and diagnosis helpers (unit tested)
utils/             Client-side helpers (theme, tokens, mailto)

Contributing

Issues and pull requests are welcome at https://github.com/geprog/media-access-manager. Before opening one, please run pnpm lint, pnpm typecheck and pnpm spelling; AGENTS.md describes the conventions this project follows – they apply to humans and AI assistants alike.

License

MIT © GEPROG GmbH

About

A small web app that can be used to provide restricted access to corporate media via providers like Vimeo or Youtube

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages

Generated from geprog/nuxt-template