{"id":24495553,"url":"https://github.com/talpitoo/dreamingsheep","last_synced_at":"2026-07-04T16:00:42.430Z","repository":{"id":355372765,"uuid":"1227387144","full_name":"talpitoo/dreamingsheep","owner":"talpitoo","description":"A free, open-source dream journal - your dreams stay private. Live at https://dreamingsheep.net 🐏","archived":false,"fork":false,"pushed_at":"2026-07-02T21:06:46.000Z","size":35591,"stargazers_count":0,"open_issues_count":12,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-07-02T22:26:46.623Z","etag":null,"topics":["blitzjs","dream-journal","dream-tracker","lucid-dreaming","nextjs","prisma","typescript"],"latest_commit_sha":null,"homepage":"https://dreamingsheep.net","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/talpitoo.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":"ROADMAP.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-02T16:01:42.000Z","updated_at":"2026-07-02T21:00:57.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/talpitoo/dreamingsheep","commit_stats":null,"previous_names":["talpitoo/dreamingsheep"],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/talpitoo/dreamingsheep","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/talpitoo%2Fdreamingsheep","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/talpitoo%2Fdreamingsheep/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/talpitoo%2Fdreamingsheep/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/talpitoo%2Fdreamingsheep/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/talpitoo","download_url":"https://codeload.github.com/talpitoo/dreamingsheep/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/talpitoo%2Fdreamingsheep/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35127443,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-04T02:00:05.987Z","response_time":113,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["blitzjs","dream-journal","dream-tracker","lucid-dreaming","nextjs","prisma","typescript"],"created_at":"2025-01-21T20:27:53.511Z","updated_at":"2026-07-04T16:00:42.421Z","avatar_url":"https://github.com/talpitoo.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"![dreamingsheep](https://dreamingsheep.net/assets/cover1200x630.jpg \"dreamingsheep\")\n\n# 🐏 _dreamingsheep_\n\nTwo ways to run it locally — pick one route and read only that section:\n\n- 💻 **natively** — Node.js + PostgreSQL on your machine; the everyday development setup (hot reload via `blitz dev`)\n- 🐋 **everything in Docker** — the only prerequisite is Docker; app, database and S3 mock all run in containers\n\nEither way, the 🪣 **local dev services** section covers running just the S3 mock\n(and/or PostgreSQL) in Docker — handy companions for the native route.\n\n## 💻 Getting Started natively (Node.js + PostgreSQL on your machine)\n\n1. Install Node.js (e.g. https://www.digitalocean.com/community/tutorials/how-to-install-node-js-on-ubuntu-20-04).\n2. Install PostgreSQL (e.g. https://www.digitalocean.com/community/tutorials/how-to-install-postgresql-on-ubuntu-20-04-quickstart).\n3. Run PostgreSQL with the default `postgres` user: `sudo -u postgres psql`.\n4. Create a password for the default `postgres` user: `ALTER USER postgres WITH PASSWORD '\u003cYOUR_DB_PASSWORD\u003e';`\n5. Copy `.env.example` to `.env.local` and fill in your values. See [.env.example](.env.example) for all required variables (database URL, session/JWT secrets, AWS S3, Gmail OAuth2, reCAPTCHA, etc.).\n6. `nvm use 18`\n7. Install Blitz.js: `npm install -g blitz` (https://blitzjs.com/docs/get-started).\n8. Install Yarn: `npm install -g yarn`\n9. Install the dependencies: `yarn install`.\n10. (optional) in PostgreSQL `DROP DATABASE dreamingsheep;` and `\\l` to make sure it is dropped.\n11. `npx prisma generate`\n12. `blitz prisma migrate dev`\n13. `blitz db seed`\n\nRun your app in the development mode.\n\n14. `blitz dev`\n15. Open [localhost:3000](http://localhost:3000) with your browser to see the result — log in with the seeded demo user `zhuangzi@dreamingsheep.net` / `zhuangzi`.\n16. (optional) Symbol image uploads need an S3 bucket — either real AWS credentials in `.env.local`, or the 🪣 local S3 mock below (no AWS account needed).\n17. (optional) If you want to test emails 1) sign up with a real email (you should receive a welcome email with a confirmation code), then sign out and initiate the forgot password flow (you should receive a forgot password email with a token). Requires the Gmail OAuth2 values in `.env.local`.\n18. For contribution guidelines, see [CONTRIBUTING.md](CONTRIBUTING.md). For the project roadmap, see [ROADMAP.md](ROADMAP.md).\n\n## 🐋 Getting Started with Docker (the only prerequisite is Docker)\n\nEverything — app, PostgreSQL and the S3 mock — runs in containers via\n[docker-compose.production.yml](docker-compose.production.yml) +\n[docker-compose.local.yml](docker-compose.local.yml). No Node.js, PostgreSQL or\nAWS account needed on your machine. The compose setup mirrors a production-style\ndeployment, but note that **production does not actually run Docker** (it's a plain\nEC2 box) — the compose file is kept as a future deployment option and as the\nquickest way to try dreamingsheep locally.\n\nThe app container uses `network_mode: host`, so it reaches everything under\n`localhost` — your `.env.local` values work unchanged in and out of Docker.\n\n1. Install Docker (with the Compose v2 plugin — the commands below use `docker compose`, not the old `docker-compose`).\n2. (optional) Run `sudo usermod -aG docker \u003cusername\u003e` (then log out, log in) or run all docker commands with `sudo`.\n3. Create your env file — for the all-Docker route this minimal recipe is enough:\n\n```sh\ncp .env.example .env.local\n```\n\n\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;then edit `.env.local` and set only:\n\n```sh\nDATABASE_URL=postgresql://postgres:postgres@localhost:5432/dreamingsheep\nSESSION_SECRET_KEY=\u003cpaste the output of: openssl rand -hex 16\u003e\nJWT_SECRET=\u003cpaste the output of: openssl rand -hex 64\u003e\n# ...and uncomment the six KEY=value lines of the \"Local S3 mock\" block, so symbol\n# image uploads work out of the box (keep the ## description lines commented —\n# docker compose parses this file strictly)\n```\n\n\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;Everything else (AWS, Gmail, reCAPTCHA) can stay empty locally — sign in with the seeded demo user instead of signing up.\n\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;⚠️ If you use a different DB password: the compose PostgreSQL initializes from `POSTGRES_PASSWORD` (default `postgres`), and the password is baked into the volume on **first initialization only** — changing it later requires `docker volume rm volume-postgres-dreamingsheep` (wipes the DB!).\n\n4. **Free up port 5432** — the compose PostgreSQL maps it, and with `network_mode: host` the app connects to whatever answers on `localhost:5432`. If a host PostgreSQL keeps running, the dockerized app will silently talk to _it_ instead of the container:\n\n```sh\nsudo lsof -i :5432               # who owns the port?\nsudo systemctl stop postgresql   # stop the host PostgreSQL for the Docker session\n# later: sudo systemctl start postgresql\n```\n\n5. Build the app image (first time and after code or `NEXT_PUBLIC_*` changes — takes a few minutes). Two caveats: the build **copies `.env.local` into the image** and `NEXT_PUBLIC_*` values are inlined into the JS bundle at build time — so set the S3 mock block _before_ building, and never push the image to a registry (it contains your secrets):\n\n```sh\ndocker compose -f docker-compose.production.yml build\n```\n\n6. Start the full stack (app + PostgreSQL + S3 mock), then migrate + seed the fresh database (first time only):\n\n```sh\ndocker compose -f docker-compose.production.yml -f docker-compose.local.yml up -d\n\ndocker exec -it docker-dreamingsheep bash\nblitz prisma migrate deploy   # applies the committed migrations (non-interactive)\nblitz db seed                 # demo users (zhuangzi/zhuangzi) + symbols + dreams\nexit\n```\n\n7. Open [localhost:3000](http://localhost:3000) and you should see the dreamingsheep landing page. Log in with the seeded demo user `zhuangzi@dreamingsheep.net` / `zhuangzi`.\n8. Try the symbol image uploads: Symbols page → **New symbol** → add a picture — upload, preview, quota and delete all run against the S3 mock. Browse the bucket at [localhost:9001](http://localhost:9001) (login `test` / `test1234`).\n9. (optional) `docker compose -f docker-compose.production.yml -f docker-compose.local.yml down` stops and removes the containers (the DB + S3 volumes survive; add `-v` to wipe them).\n10. (optional) All the docker images will require ~12GB of space (`docker images`):\n\n```\nREPOSITORY                  TAG      SIZE\ndreamingsheep-blitzjs-app   latest   11GB\npostgres                    13.4     533MB\nminio/minio                 latest   241MB   (S3 mock)\nminio/mc                    latest   117MB   (S3 mock init)\n```\n\n11. (optional) Other useful docker commands:\n\n```sh\ndocker ps\ndocker compose -f docker-compose.production.yml ps\ndocker images\ndocker rmi \u003cid\u003e\ndocker logs docker-dreamingsheep\ndocker logs docker-postgres-dreamingsheep\ndocker exec -it docker-postgres-dreamingsheep psql -U postgres dreamingsheep   # poke the DB directly\ndocker system prune -a\ndocker volume ls\ndocker volume rm volume-postgres-dreamingsheep   # wipe the dockerized DB (re-migrate + re-seed after)\ndocker compose -f docker-compose.production.yml down --rmi all\n```\n\n## 🪣 Local dev services in Docker (S3 mock + PostgreSQL)\n\nCompanions for the 💻 native route: run only the services in Docker while the app\nruns on your machine with `blitz dev`. (The 🐋 all-Docker route above already\nincludes them.)\n\n**S3 mock** — symbol image uploads without an AWS account (issue\n[#13](https://github.com/talpitoo/dreamingsheep/issues/13)).\n[docker-compose.local.yml](docker-compose.local.yml) ships a **MinIO** mock\n(LocalStack's free Docker images were discontinued in March 2026) plus a one-shot\ninit container that creates the `dreamingsheep-local` bucket and opens it for\nanonymous downloads (the browser loads symbol images directly from the bucket URL).\n\n1. Start it:\n\n```sh\ndocker compose -f docker-compose.local.yml up -d\n```\n\n2. Point the app at it — uncomment the six `KEY=value` lines of the \"Local S3 mock\" block in `.env.local` (see [.env.example](.env.example)):\n\n```sh\nS3_ENDPOINT=http://localhost:9000\nAWS_ACCESS_KEY_ID=test\nAWS_SECRET_ACCESS_KEY=test1234\nAWS_REGION=us-east-1\nS3_BUCKET=dreamingsheep-local\nNEXT_PUBLIC_S3_BUCKET=http://localhost:9000/dreamingsheep-local\n```\n\n3. Restart the dev server (`blitz dev`) and create a custom symbol with a picture on the Symbols page. Browse the bucket at [localhost:9001](http://localhost:9001) (login `test` / `test1234`).\n4. **Production is unaffected**: the S3 client only switches endpoints when `S3_ENDPOINT` is set — leave it unset outside local development.\n\n**PostgreSQL** — if you'd rather not install it natively, run just the database\nfrom the production compose file (mind the port-5432 and password notes in the 🐋\nsection above):\n\n```sh\ndocker compose -f docker-compose.production.yml up -d postgres\n```\n\n## 🧪 Testing\n\n- `npm test` — unit tests (Vitest): pure helpers (search where-builder, chart/sleep\n  aggregations) and zod validation schemas. Fast, no database or server needed.\n- `npm run test:watch` — the same in watch mode.\n- `npm run test:e2e` — end-to-end tests (Vitest + puppeteer) driving the real app in\n  headless Chromium: login, dream/symbol CRUD, search, settings toggles and their\n  effect on the Stats page, public pages. Requires a **running dev server**\n  (`npm run dev`, or set `E2E_BASE_URL`) and a **seeded local DB** (`blitz db seed`\n  — the flows log in as the demo user and clean up after themselves).\n- CI (`.github/workflows/test.yml`) runs lint, type-check and unit tests on every\n  PR; the E2E suite is local-only for now.\n- Philosophy (see issue #2): test the things that actually break — edge cases over\n  coverage percentages.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftalpitoo%2Fdreamingsheep","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftalpitoo%2Fdreamingsheep","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftalpitoo%2Fdreamingsheep/lists"}