mirror of
https://github.com/LukeHagar/pypistats.dev.git
synced 2025-12-06 04:21:09 +00:00
Update README.md to reflect project rebranding to PyPIStats.dev and enhance deployment instructions with Docker Compose details, environment variable setup, and API overview.
This commit is contained in:
Luke Hagar
87
README.md
87
README.md
@@ -1,38 +1,79 @@
|
|||||||
# sv
|
# PyPIStats.dev
|
||||||
|
|
||||||
Everything you need to build a Svelte project, powered by [`sv`](https://github.com/sveltejs/cli).
|
PyPIStats.dev is an open-source, SvelteKit-based replacement for PyPI Stats. It provides fast, on-demand Python package download analytics sourced from BigQuery, backed by PostgreSQL and Redis. The platform exposes a clean web UI and a standards-friendly JSON API suitable for programmatic use.
|
||||||
|
|
||||||
## Creating a project
|
Key features:
|
||||||
|
- On-demand per-package ingestion from BigQuery (no cron required)
|
||||||
|
- Idempotent database writes with Prisma and per-day/per-package dedupe locks (Redis)
|
||||||
|
- Recent (day/week/month) stats computed on-demand from overall series
|
||||||
|
- Additional dimensions: system, Python versions, installer tool
|
||||||
|
- Single Docker Compose stack for Postgres + Redis + app
|
||||||
|
|
||||||
If you're seeing this, you've probably already done this step. Congrats!
|
## Deploy and run with Docker Compose (self-contained)
|
||||||
|
|
||||||
```sh
|
This repository is designed to deploy with `docker compose` as the primary (and only) method. The stack includes the web app, Postgres, and Redis.
|
||||||
# create a new project in the current directory
|
|
||||||
npx sv create
|
|
||||||
|
|
||||||
# create a new project in my-app
|
1) Provide environment variables
|
||||||
npx sv create my-app
|
|
||||||
|
- Recommended via a `.env` file at repo root (or in your platform’s UI — Coolify supports adding envs/secrets directly):
|
||||||
|
|
||||||
|
```
|
||||||
|
DATABASE_URL=postgresql://pypistats:pypistats@db:5432/pypistats?schema=public
|
||||||
|
REDIS_URL=redis://redis:6379
|
||||||
|
|
||||||
|
# BigQuery
|
||||||
|
GOOGLE_PROJECT_ID=your-project
|
||||||
|
# Prefer JSON for container environments
|
||||||
|
GOOGLE_APPLICATION_CREDENTIALS_JSON={"type":"service_account","project_id":"...","private_key_id":"...","private_key":"-----BEGIN PRIVATE KEY-----\\n...\\n-----END PRIVATE KEY-----\\n","client_email":"...","client_id":"...","auth_uri":"https://accounts.google.com/o/oauth2/auth","token_uri":"https://oauth2.googleapis.com/token","auth_provider_x509_cert_url":"https://www.googleapis.com/oauth2/v1/certs","client_x509_cert_url":"..."}
|
||||||
```
|
```
|
||||||
|
|
||||||
## Developing
|
2) Start the stack locally
|
||||||
|
|
||||||
Once you've created a project and installed dependencies with `npm install` (or `pnpm install` or `yarn`), start a development server:
|
```
|
||||||
|
docker compose up --build
|
||||||
```sh
|
|
||||||
npm run dev
|
|
||||||
|
|
||||||
# or start the server and open the app in a new browser tab
|
|
||||||
npm run dev -- --open
|
|
||||||
```
|
```
|
||||||
|
|
||||||
## Building
|
The app will be available at http://localhost:3000
|
||||||
|
|
||||||
To create a production version of your app:
|
3) Running in Coolify
|
||||||
|
|
||||||
```sh
|
- Add this repository as an application in Coolify and choose Docker Compose.
|
||||||
npm run build
|
- In the service configuration, add your environment variables (DATABASE_URL, REDIS_URL, GOOGLE_PROJECT_ID, GOOGLE_APPLICATION_CREDENTIALS_JSON) via Coolify’s UI. Coolify will inject them for you — no file changes needed.
|
||||||
|
- Deploy. The app will run the database migrations on startup and serve on port 3000.
|
||||||
|
|
||||||
|
## API overview
|
||||||
|
|
||||||
|
All endpoints return JSON. Examples (for package `numpy`):
|
||||||
|
- GET `/api/packages/numpy/recent?period=month`
|
||||||
|
- GET `/api/packages/numpy/overall?mirrors=false`
|
||||||
|
- GET `/api/packages/numpy/python_major?version=3`
|
||||||
|
- GET `/api/packages/numpy/python_minor?version=3.11`
|
||||||
|
- GET `/api/packages/numpy/system?os=Linux`
|
||||||
|
- GET `/api/packages/numpy/installer`
|
||||||
|
|
||||||
|
Each API request triggers on-demand ingestion if the package is missing or stale (up to yesterday), then serves from the database and cache.
|
||||||
|
|
||||||
|
## Development with Compose
|
||||||
|
|
||||||
|
- Dev server (hot reload) using the included dev override:
|
||||||
|
|
||||||
|
```
|
||||||
|
docker compose -f docker-compose.yml -f docker-compose.dev.yml up --build
|
||||||
|
# App at http://localhost:5173
|
||||||
```
|
```
|
||||||
|
|
||||||
You can preview the production build with `npm run preview`.
|
- Prisma migrations during development:
|
||||||
|
|
||||||
> To deploy your app, you may need to install an [adapter](https://svelte.dev/docs/kit/adapters) for your target environment.
|
```
|
||||||
|
docker compose -f docker-compose.yml -f docker-compose.dev.yml exec web pnpm prisma migrate dev
|
||||||
|
```
|
||||||
|
|
||||||
|
## Contributing
|
||||||
|
|
||||||
|
Issues and PRs are welcome. Please ensure:
|
||||||
|
- Type-safe changes (Prisma and TypeScript) with clean lints
|
||||||
|
- No secrets committed; configure via `.env`/`env_file`
|
||||||
|
|
||||||
|
## License
|
||||||
|
|
||||||
|
MIT
|
||||||
Reference in New Issue
Block a user