Quickstart
Run Pinwren with Docker, create a project and see your first pinned comment in about five minutes.
You need Docker with Compose. The stack is two containers: Pinwren and Postgres 17.
Get the compose file and set three values
git clone https://github.com/Krithik-m-codes/pinwren.git && cd pinwren
cp docker/.env.example docker/.envOpen docker/.env and fill in the three required values:
# The URL people open and the widget calls. No trailing slash.
PINWREN_URL=http://localhost:3000
# openssl rand -base64 48
PINWREN_SECRET=<a long random string, at least 32 characters>
# openssl rand -hex 24
POSTGRES_PASSWORD=<another random string>http://localhost:3000 is fine for a first try on your own machine. For a real install use your public HTTPS
URL, e.g. https://feedback.example.com, behind a reverse proxy.
Start it
Each release publishes a multi-arch image (amd64, arm64). Pin a version in docker/.env and start without
--build:
PINWREN_IMAGE=ghcr.io/krithik-m-codes/pinwren:0.1.0docker compose -f docker/compose.yml --env-file docker/.env up -dDatabase migrations run automatically when the app starts. Check it is up:
curl http://localhost:3000/api/health
# {"ok":true,"version":"0.1.0"}Create your account and first project
Open PINWREN_URL and create the first account. The first account on a new server is its instance
admin, so email, security and licence settings are open to you straight away — there is no setup token to
find in the logs. (Keep the server private until you have signed up; the compose file only listens on
127.0.0.1.) The setup screen then asks for a workspace name, a first project, your website
domain — the project's first allowed site — and what the site is for: a public website keeps bug
reports private, a staging or client review site shows reviewers each other's pins.
Sign-up is closed after the first account
Anyone else needs an invitation from Settings › Users. To let anyone sign up, set
PINWREN_DISABLE_SIGNUP=false in docker/.env and restart.
Set up email
Open Settings › Email, enter your SMTP server (host, port, security, user, password and from address) and click Send test email. From then on every new report is emailed to the team, and reporters who left an address get a confirmation and updates. See Email for provider settings.
Allow your site
In the project's Install tab, under Allowed sites, list every hostname that will load the widget, for
example www.example.com, *.staging.example.com or localhost:5173. Requests from any other origin are
refused with 403 ORIGIN_NOT_ALLOWED, and the tab lists them — "Blocked a request from https://… 2 min ago" —
with an Allow button. It also has a tester that tells you whether a URL is allowed.
Paste the snippet
Copy the snippet from the Install tab and add it before </body> on every page:
<script src="https://feedback.example.com/widget.js" data-project="pk_…" async></script>The project key is public by design — it only works from your allowed sites. The Install tab also has
Next.js, Google Tag Manager, npm and React versions, all prefilled with your key and server address, and a
npx @pinwren/cli doctor command that checks the setup from your terminal.
Leave a pin
Reload your site. The launcher appears in the bottom-right corner, and the Install tab switches from Waiting for your site to Connected. Press C (or open the launcher and choose comment), click an element, write a comment and send it. It appears in the dashboard inbox straight away. Report a bug the same way and the team gets an email with the screenshot, page, browser and a link. A checklist on the inbox tracks these first steps until they are all done.