Lightning TipCards are a tip (or gift) card system, where you can fund tip cards via the lightning network and the gifted person can redeem the funded cards. The gifted person gets a short introduction to bitcoin and a lightning app recommendation to start their journey into the bitcoin rabbit hole.
It is an open-source project developed and operated for the benefit of the Bitcoin community, with a focus on "How to gentle orange pill nocoiners" - and without warranty of any kind.
LNbits is used for the wallet and lightning payments in the background.
- Youtube: How to use lightning tip cards - DE
- Youtube: How to use lightning tip cards - EN
- Youtube: How to create your set of lightning tip cards - DE
- Youtube: How to create your set of lightning tip cards - EN
#satohsiengineeringcrew
is #happy2help
- nodejs 16.18.0 LTS
- npm
- docker (recommended for redis setup, see below)
npm install
If you are working at Satoshi Engineering, please configure your GIT repo to use the GIT hooks from the directory .githooks
:
git config core.hooksPath .githooks
- Setup a redis database on localhost. You can do that by using docker (https://hub.docker.com/_/redis). Just make sure to expose the port 6379 to the host. The modules
rejson
andredisearch
are required. - Setting up redis commander is also recommended: https://hub.docker.com/r/rediscommander/redis-commander
- See Example
- Create your own wallet on https://demo.lnbits.com/ or set your preferred lnbits instance via the env variable
LNBITS_ORIGIN
inbackend/.env.local
(see below). - Create a
backend/.env.local
file (or copy it frombackend/.env
) and set the following variables:TIPCARDS_ORIGIN
probably http://localhost:5173 -> where your frontend will be servedTIPCARDS_API_ORIGIN
probably http://localhost:4000 -> where your backend will be servedLNBITS_INVOICE_READ_KEY
paste from your lnbits wallet: get this from https://demo.lnbits.com/wallet and clicking on "API info"LNBITS_ADMIN_KEY
paste from your lnbits wallet: get this from https://demo.lnbits.com/wallet and clicking on "API info"
- You can look up additional optional variables in
.env.example
Per default the backend loads the backend/.env
and backend/.env.local
files. If you need to start the backend for integration tests you have to use a different env file. Run the backend using npm run backend-dev -- --envIntegrationTest
which will also use the file backend/.env.integrationTest
. You can also add the parameter to all other commands (cli, drizzle-migration, etc.).
You can run backend integration tests locally, including starting the local backend, in one command by running the helper script ./backend-integration-tests.sh
. This command uses the backend/.env.integrationTest
env file (see Integration Test Env File).
Alternately if you want to run specific tests you could do:
# create custom env file for testing + startup backend using it
vi backend/.env.integrationTest
npm run backend-dev -- --envIntegrationTest
# run a specific test using .env.integrationTest
npx vitest run --config ./backend/vitest.config.ts ./backend/tests/integration/your/custom/test.ts
- Create a
frontend/.env.development.local
file (or copy it fromfrontend/.env.development
) and add the following variable:VITE_BACKEND_API_ORIGIN
probably http://localhost:4000 -> where your frontend will be served
If you want to test the tipcards on your local machine, here are some hints
- Fund your https://demo.lnbits.com/wallet with 1 - 100sats. The tipcard redeeming creates a lightning invoice via lnbits and there are transaction costs.
- It won't work with your smartphone, because the development setup restricted to localhost. (And if you use
vite --host
to expose the port, your lightning apps will refuse to work because there is no ssl connection)- We use BlueWallet Deskop app for testing (it can access localhost)
Ngrok is used to expose you local environment to the web. This is needed to test auth/backend features with your phone (e.g. paying invoices, logging in via lnurl-auth).
- Copy backend/.env into backend/.env.local
- Go to https://ngrok.com and create an account
- Go to https://dashboard.ngrok.com/get-started/setup, copy your authtoken and add it to backend/.env.local
Either use the dev-tip-cards.sh
script:
- Run
./dev-tip-cards.sh
and after it finishes copy the displayed ngrok url to your browser.
Or execute the following steps manually:
- Run
npm run backend-proxy
. This starts an express server that proxies all requests to your other services that we will start later. - Run
npm run backend-ngrok
. Then copy the ngrok url that will be pasted in the console (something like https://cdb6-62-178-206-224.ngrok.io). - Open backend/.env.local and set the ngrok url (from the previous point) for
TIPCARDS_ORIGIN
andTIPCARDS_API_ORIGIN
as this is now your public URL for your phone and lnbits webhooks. - Open frontend/.env.development.local and set
VITE_BACKEND_API_ORIGIN=
to an empty string. The API origin will be the same as the frontend origin (the ngrok URL). - Run
npm run backend-dev
- Run
npm run frontend-dev
As LNURL-auth tokens are based on the domain of the website where they are used, you will not be able to login with the same user after stopping and restarting the ngrok proxy.
For additional developer tasks, scripts can be found in scripts.
Start the frontend server on http://localhost:5173
npm run frontend-dev
Start the backend server on http://localhost:4000
npm run backend-dev
Deployment is done via Gitlab CI/CD, see .gitlab-ci.yml
If you like this project, please adapt the landingpage to your local stores, that accept bitcoin or even extend it. Why not send some tip love?