Vitafolio documentation

Everything about Vitafolio in one place: how to use it, how it is built, how it keeps people's data safe and how to run your own copy.

Contents

• Using Vitafolio
• Architecture
• Data model
• Accounts and sign-in
• Profiles and handles
• CVs and visibility
• Files, media and limits
• The LaTeX editor
• Security
• Privacy
• Search and sharing
• Configuration
• Local development
• Deployment
• Operations
• Testing and quality checks
• Design decisions
• Troubleshooting
• Frequently asked questions

Using Vitafolio

Getting started

1. Create an account with an email address and password. Where the site offers them, you can also continue with Google, GitHub, Microsoft or LinkedIn.
2. Confirm your email address from the link sent to you. Nothing can be created until it is confirmed.
3. Your first CV, called "My CV", is ready on the My CVs page.

Your profile

The Profile page holds what every CV shares: your photo, headline, bio, location, university, availability and links. Choose a photo, frame it in the circle by dragging, zooming or using the arrow keys, then upload it. Paste one link per line; well-known sites such as GitHub, LinkedIn, ORCID and Google Scholar are named for you.

Your profile lives at /@your-handle. It can be public, unlisted (only people with the link) or private.

Building a CV

Each CV has five tabs:

Themes are Classic, Modern, Minimal and Plain. Plain is designed to be read easily by screen readers and the applicant tracking systems employers use to scan CVs.

Sharing a CV

Every CV has its own address. From the CV page you can copy the link, show a QR code for printed copies, download a generated PDF and open any attached file. When the link is posted on a social site or in a chat, a preview card shows your photo, name, headline and top skills.

On My CVs, each CV shows how many people viewed it over the last 30 days and which sites sent them. Your own visits are never counted.

Keeping your account safe

Settings (from the account menu in the top corner) has a page for each setting: public profile, photo, handle, name and email, password and two-factor authentication, passkeys, connected accounts, signed-in devices and your data, where you can download everything as JSON or delete your account.

Analytics

Analytics (also from the account menu) shows CV views, profile views, PDF downloads and QR code scans for the last 7, 30 or 90 days, with the previous period for comparison, views per CV, where visitors came from and the busiest day. Every chart has a table with the same numbers. Each visitor counts once a day, using a code that changes daily. Your own visits never count.

Help and documentation

The Help centre at /help has guides for every part of the site and a search box. /features, /contact, /changelog and /docs (this document) are linked from the footer.

Architecture

Vitafolio is a server-rendered Laravel application. Pages are Blade templates styled with Tailwind CSS. Small interactive parts use Alpine.js. The few rich widgets (the LaTeX studio, the section order editor and the photo cropper) are Vue components mounted as islands, so a page without one never downloads Vue.

flowchart LR
    Browser -->|HTTPS| Proxy[Hosting proxy and Cloudflare]
    Proxy -->|HTTP| App[FrankenPHP and Laravel]
    App --> DB[(MySQL)]
    App -->|signed API calls| Cloudinary[(Cloudinary)]
    App -->|mail| Resend
    App -.->|errors| Sentry
    Browser -->|engine files, first compile only| Engine[LaTeX engine host]
    Scheduler[Nightly scheduler] -->|POST /cron with a token| App

Data model

erDiagram
    users ||--o{ cvs : owns
    users ||--o{ social_accounts : "signs in with"
    users ||--o{ passkeys : "signs in with"
    users ||--o{ handle_history : "used to be"
    cvs ||--o| cv_documents : "has a file"
    cvs ||--o{ projects : shows
    cvs }o--o{ tags : "tagged with"
    cvs ||--o{ cv_views : counts
    users ||--o{ profile_views : counts
    cvs ||--o{ reports : receives

Every table has a primary key, so the schema runs on database hosts that require one.

Accounts and sign-in

• Passwords need at least 10 characters with a letter and a number. Passwords found in known breaches are refused; only a short hash prefix leaves the server for that check.
• Email verification is required before anything can be created.
• Two-factor authentication uses an authenticator app with recovery codes.
• Passkeys sign in with a fingerprint, face or device PIN. Adding or removing one needs a password confirmed within the last three hours.
• Sign-in providers are Google, GitHub, Microsoft and LinkedIn. Each one only appears once its keys are set.

[!IMPORTANT] A provider sign-in joins an existing account with the same email only when the provider confirms the address is verified. Google and LinkedIn say so explicitly and GitHub only shares verified addresses. Microsoft gives no such promise for every organisation, so it never joins an account by email; it can still be connected from the account page while signed in.

Two-factor accounts still answer their challenge after a provider sign-in. Suspended accounts are refused on every route: password, passkey and provider. An account always keeps at least one way in, so the last provider cannot be disconnected without a password or passkey.

Profiles and handles

New accounts get a handle made from their name, such as /@alex-morgan. It can change once every 30 days. The old handle redirects to the new one for 30 days and nobody else can claim it during that time, which stops someone taking over a known handle to pose as its previous owner. A list of reserved words (such as admin and support) can never be used.

A profile can be public (listed and searchable), unlisted (link only) or private (owner only). A private profile also takes its CVs out of the directory and out of search engines.

CVs and visibility

A public CV is also kept out of the directory and search when its owner's profile is private, their email is unverified or the account is suspended. Owners and admins always see a banner saying which of these applies.

Files, media and limits

CV files (uploads and compiled LaTeX PDFs) are stored on Cloudinary as authenticated assets: their addresses cannot be guessed and cannot be opened without a signature. Vitafolio checks the viewer may see the CV, then fetches the file and passes it on, so a private CV's file stays private. Without Cloudinary configured, files are stored in the database instead.

Project images and videos are public assets on Cloudinary, delivered in the best format for each browser. Profile photos are re-encoded to a 600 pixel JPEG and stored in the database, because they are small and appear on every directory card.

Every upload is checked by its content rather than its name: PDFs must start with the PDF signature and Word files must be real .docx packages. Images are decoded and re-encoded, which drops anything hidden inside them along with location and camera data. Phone photos are turned upright using their EXIF tag first, so the crop tool and the stored photo always agree.

Deleting a file, a project, a CV or a whole account also deletes its copies on Cloudinary.

The LaTeX editor

The editor uses CodeMirror for the source and BusyTeX, TeX Live compiled to WebAssembly, to compile in the browser with pdfLaTeX, XeLaTeX or LuaLaTeX. Nothing is sent to a server until the owner saves. The engine files (about 120 MB, cached after the first compile) are hosted separately and named by LATEX_ASSETS_URL.

Four starter templates fill in the owner's details: Classic, Compact, Modern and Academic. Saving stores the source. When a compile has succeeded, saving also attaches the PDF as the CV's file. Ctrl+Enter compiles and Ctrl+S saves (Cmd on a Mac). A plain text box can replace the code editor for anyone who finds it easier with a screen reader.

Security

Report a vulnerability through the security policy. Never open a public issue for one.

Privacy

• Visitors can message a CV's owner without seeing their email address. The owner sees the visitor's address only when they reply.
• View counts use a hash that changes daily, so a visitor cannot be followed from one day to the next.
• Site analytics, where enabled, are Cloudflare Web Analytics: no cookies and no tracking across sites.
• Photos from sign-in providers are copied once on request, never loaded from the provider's site.
• Every account can download all its data as JSON and delete itself, which removes its files too.

Search and sharing

• Sitemap at /sitemap.xml lists the main pages, public profiles and public CVs. robots.txt points to it.
• IndexNow tells Bing, Yandex and other participating search engines when a public CV or profile changes, goes private or is deleted. It runs after the response, so saving is never slowed down. Google reads the sitemap instead.
• Structured data marks profiles and CVs up as a ProfilePage about a Person.
• Share images are generated for each CV with the photo, name, headline and top skills.
• QR codes point at each CV for printed copies.
• /.well-known/security.txt gives the security contact, with an expiry that renews itself.

Configuration

Copy .env.example to .env. Laravel's own settings are documented there; these are Vitafolio's.

Each provider's callback address is the site address followed by /auth/<provider>/callback, for example /auth/google/callback. Microsoft sign-in uses the common tenant by default so personal, work and school accounts can all use it; set MICROSOFT_TENANT to restrict it.

Local development

The README has the quick start. A few more details:

• npm run dev runs Vite with hot reload. While it runs, the strict content security policy is relaxed so the dev server can inject its scripts.
• With MAIL_MAILER=log, every email (verification, password reset, messages and report alerts) is written to storage/logs/laravel.log.
• The service worker only registers in a production build, so development never serves stale files.
• scripts/brand-assets.sh needs rsvg-convert (from librsvg) and Python 3.

Deployment

The Dockerfile builds a production image in three stages: front-end assets with Node, PHP dependencies with Composer, then a final FrankenPHP image on Alpine Linux that runs as an unprivileged user. On every start, docker/start.sh caches the configuration, routes, views and events, runs any new migrations and then starts the server on PORT. A failed migration stops the start, so a broken release never serves traffic.

To deploy on a container host such as Render:

1. Create a MySQL 8 database and note its host, port, name, user and password.
2. Create a web service from this repository using the Dockerfile.
3. Set APP_KEY (from php artisan key:generate --show), APP_URL, the DB_* values and any optional services from the configuration table. Set SESSION_SECURE_COOKIE=true.
4. If the database requires TLS, upload its CA certificate as a secret file and point MYSQL_ATTR_SSL_CA at it.
5. Set the health check path to /up.
6. After the first deploy, open a shell and run php artisan vitafolio:make-admin you@example.com.

[!WARNING] Keep APP_KEY safe. It encrypts sessions and two-factor secrets and salts view counts. To rotate it, set APP_PREVIOUS_KEYS to the old key, set the new key, redeploy, then drop the old key after SESSION_LIFETIME has passed. Set PASSKEYS_USER_HANDLE_SECRET before the first passkey is created and never change it. Otherwise every passkey stops matching its account.

Rotating secrets

The LaTeX engine files come from the texlyre-busytex release. Host them anywhere that serves static files with CORS allowed, such as GitHub Pages. Then set LATEX_ASSETS_URL to that address.

Operations

Incident response

If personal data may have been exposed, lost or changed without permission:

1. Contain it. Rotate every secret that may be involved using the table above, run php artisan tinker --execute="DB::table('sessions')->truncate(); DB::table('password_reset_tokens')->truncate();" from a shell on the host so every session and reset link is dead. Suspend any account being misused.
2. Assess it. Work out what data, how many people, for how long and what the effect on them could be. The audit log and Sentry are the first places to look.
3. Record it. Write down the date you became aware, the facts, the effect and what was done, whether or not it is reported. UK GDPR requires this record for every breach.
4. Decide on reporting. If the breach is likely to put people at risk, report it to the ICO within 72 hours of becoming aware of it.
5. Tell the people affected without undue delay when the risk to them is high, saying what happened, what it means for them and what to do, such as resetting their password.
6. Fix the cause and write a short post-mortem in the changelog or an issue.

Testing and quality checks

php artisan test runs the feature and unit tests on an in-memory SQLite database, with no front-end build or outside services needed. They cover ownership, visibility, handles, uploads and Cloudinary storage, security headers, every sign-in route including providers and passkeys, background jobs, link parsing and image handling.

CI runs every check on each pull request, plus composer audit, npm audit, a Trivy scan of the production image and a Gitleaks scan for committed secrets.

Design decisions

Troubleshooting

Frequently asked questions

Can I have more than one CV? Yes, up to ten, each with its own address and privacy setting.

Who can see a private CV? Only you and the site's moderators.

Do recruiters need an account? No. Public and unlisted CVs open for anyone with the link.

Can I use my own CV file? Yes. Upload a PDF or Word file. The LaTeX editor can also write and compile one. A CV can have both built content and a file.

What happens to my data if I delete my account? Your profile, CVs, files, photos and connected sign-ins are deleted straight away, including the copies on Cloudinary.

Can I move my CV elsewhere? Yes. Export any CV as JSON Resume, an open format other tools can read. The account page also downloads all your data at once.