Your next shot.
A better memory.

1. Open github.com/signup. Use an email address you can access, choose a username and create a unique password. Save it in your password manager.
2. Complete GitHub’s verification prompts, then open the email from GitHub and verify your email address. A personal free account is enough to follow this guide.
3. Sign in at github.com. Use the profile picture at the top right to find your profile and settings. Keep your username handy; you will need it later.

1. Open your profile picture → Settings → Password and authentication. Find Two-factor authentication and choose to enable it.
2. Use an authenticator app on your phone. Follow GitHub’s QR-code prompts, enter the code from the app and finish the setup.
3. Download the recovery codes when prompted. Store them somewhere safe that you can access without this phone; never put them in a repository.
4. If your device supports it, add a passkey as another sign-in method after enabling 2FA. Keep a recovery option as well.
5. Protect the email account you use for GitHub, too. Try signing out and back in once so you know your login and second factor work.

1. Open github.com/aawse/myshotlog and click Fork near the top of the page.
2. Choose your personal account as the owner. Keep the repository name myshotlog, keep the main branch and create the fork.
3. Check the page address: it should now be github.com/YOUR-USERNAME/myshotlog. This is the code repository you will import into Vercel.
4. This fork is public because the original is public. That is fine for code. Do not add journal exports, target photos, tokens or passwords to it.

1. On GitHub, use the + menu → New repository. Choose your personal account as the owner.
2. Name this second repository myshotlog-data. Choose Private. Select Add a README so the main branch exists, then create the repository.
3. Look for the Private label on the repository page. Keep this repo private and avoid adding collaborators unless you deliberately want to share the full data history.
4. Write down the owner/name and branch, for example YOUR-USERNAME/myshotlog-data and main. Do not use the code fork’s name here.

1. Open GitHub Settings → Developer settings → Personal access tokens → Fine-grained tokens. Choose Generate new token.
2. Name it MyShotLog journal and choose a sensible expiration date. Set a reminder to replace the token before that date.
3. Select your personal account as resource owner. Under Repository access, choose Only select repositories, then select only myshotlog-data.
4. Under Repository permissions, set Contents to Read and write. Leave the automatically required metadata access and do not add unrelated permissions.
5. Generate the token. Copy it once into a safe password-manager entry; GitHub will not show it again. In step 9 it goes into GIT_DATABASE_TOKEN on Vercel.
6. Keep the token out of your code fork, screenshots and messages. If it is exposed, revoke it on GitHub and make a replacement.

1. Open vercel.com/signup and continue with your GitHub account. For personal, non-commercial use, review the Hobby option and its limits.
2. In your Vercel account settings, enable two-factor authentication and save the recovery codes. Follow Vercel’s own prompts.
3. From the Vercel dashboard, choose Add New → Project. Connect GitHub if asked. Grant the integration access to your myshotlog code fork; the journal repo is connected later through its token.
4. Import YOUR-USERNAME/myshotlog, not myshotlog-data. Use Next.js as the framework, the repository root as Root Directory and Node.js 24.x. Leave the app’s normal build settings in place.
5. Deploy once without the private variables. Seeing the app’s setup screen at this stage is normal.
6. Open the project’s Domains settings and note the stable production domain, such as YOUR-PROJECT.vercel.app. Use that address throughout the remaining steps, not a one-off preview deployment URL.

1. Open a new tab at https://api.github.com/users/YOUR-USERNAME, replacing YOUR-USERNAME with your GitHub username.
2. The page shows text with field names. Find login and html_url to confirm it is your profile, then check type is User.
3. Copy the number beside id. Do not copy node_id, your username or the whole page. The number is not a password, but you do not need to post it publicly.
4. Keep it for GITHUB_ALLOWED_USER_IDS in step 9. For your personal installation, enter only your own number.

https://api.github.com/users/YOUR-USERNAME

1. Open GitHub Settings → Developer settings → OAuth Apps → New OAuth App. Make sure you are creating an OAuth App, not a GitHub App.
2. For the application name, use MyShotLog personal. For Homepage URL, enter your stable HTTPS production origin from step 6, for example https://YOUR-PROJECT.vercel.app.
3. For Authorization callback URL, use the same origin followed by /auth/github/callback/. Keep the final slash. Register the application.
4. Copy the Client ID. Generate a new client secret and save it privately in your password manager.
5. In step 9 these go into GITHUB_CLIENT_ID and GITHUB_CLIENT_SECRET. Keep the secret private. This login connection does not need access to all your repositories.

https://YOUR-PROJECT.vercel.app/auth/github/callback/

1. In Vercel, open your MyShotLog app project → Settings → Environment Variables. Use the table below to add each name and value.
2. For each entry, choose Production. Use your own values instead of the uppercase placeholders. Do not include quotation marks or extra spaces around values.
3. Use a password manager to generate a separate random secret of at least 64 letters and numbers for AUTH_SESSION_SECRET. Do not reuse your GitHub password or either GitHub secret.
4. Enable Sensitive for GIT_DATABASE_TOKEN, GITHUB_CLIENT_SECRET and AUTH_SESSION_SECRET. Keep all three private. The other values still belong in Vercel settings, not in a new public configuration file.
5. Check NEXT_PUBLIC_SITE_URL: it is only https:// plus the stable domain, with no extra path, query or trailing slash. The OAuth callback has a path and a final slash; the origin variable does not.
6. Open Deployments and redeploy the current production deployment after saving the variables. Wait for Ready. Changes apply to a new deployment, not to the old one.
7. Open the stable production address again. You should now see the GitHub sign-in option instead of incomplete setup instructions.

1. At your stable production address, choose Sign in with GitHub. Check that the GitHub authorization screen identifies your own OAuth app and approve the login.
2. If you have a MyShotLog JSON backup, import it from the empty dashboard or Settings before saving a new profile. Otherwise start a new journal.
3. Open Settings. Choose the app’s language and optionally add your birth date. Save the profile. The date can be used for age-based assessments; it stays in your private journal.
4. Add a firearm if you want, then create a session with its date, location, sport, distance, target and shooting time. Record a series and save.
5. Check that the session appears in the list. Try a target photo and a JSON export. Sign out and sign back in once to check the complete flow.

1. Export a JSON backup from MyShotLog Settings regularly and before updates. Keep backups private. CSV is for spreadsheets, not a full restore.
2. Before the GitHub token expires, generate a replacement with the same narrow permissions, update GIT_DATABASE_TOKEN in Vercel and redeploy. Revoke the old token after checking the replacement.
3. For app updates, open your code fork on GitHub and use Sync fork. Review changes, then let Vercel deploy the updated production branch. Avoid changing the data repository or its prefix during an update.
4. Check provider usage and current plan limits occasionally. You manage your own accounts and installation; the code author does not receive your records.
5. Removing a record in the app does not remove old versions from Git history or existing backups. Protect the whole repository history as well as the current files.
6. If a secret leaks, revoke or rotate it, update Vercel and redeploy. Rotating AUTH_SESSION_SECRET signs everyone out. Do not post secret values when asking for help.