{"id":28521391,"url":"https://github.com/paulseperformance/earthquake-telegram-bot","last_synced_at":"2025-07-03T17:31:46.090Z","repository":{"id":293311992,"uuid":"983530184","full_name":"pAulseperformance/earthquake-telegram-bot","owner":"pAulseperformance","description":"A Telegram bot that sends notifications about earthquakes using USGS Atom feeds","archived":false,"fork":false,"pushed_at":"2025-05-15T10:50:50.000Z","size":135,"stargazers_count":0,"open_issues_count":1,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-06-09T07:56:35.308Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/pAulseperformance.png","metadata":{"files":{"readme":"readme.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-05-14T14:15:05.000Z","updated_at":"2025-05-15T10:50:53.000Z","dependencies_parsed_at":"2025-05-14T18:45:14.256Z","dependency_job_id":"e4867b8f-e272-4c6d-b064-1fc2890603ea","html_url":"https://github.com/pAulseperformance/earthquake-telegram-bot","commit_stats":null,"previous_names":["paulseperformance/earthquake-telegram-bot"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/pAulseperformance/earthquake-telegram-bot","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pAulseperformance%2Fearthquake-telegram-bot","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pAulseperformance%2Fearthquake-telegram-bot/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pAulseperformance%2Fearthquake-telegram-bot/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pAulseperformance%2Fearthquake-telegram-bot/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/pAulseperformance","download_url":"https://codeload.github.com/pAulseperformance/earthquake-telegram-bot/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pAulseperformance%2Fearthquake-telegram-bot/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":263369594,"owners_count":23456327,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":[],"created_at":"2025-06-09T07:36:08.677Z","updated_at":"2025-07-03T17:31:46.078Z","avatar_url":"https://github.com/pAulseperformance.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Earthquake Telegram Notification Bot\n\nA Telegram bot that sends real-time earthquake notifications from USGS feeds. Users can subscribe to different earthquake categories based on magnitude.\n\n## Features\n\n- Real-time earthquake notifications via Telegram\n- Customizable notification preferences by magnitude category\n- Support for multiple subscribers/chat rooms\n- Persistent storage of subscriber preferences\n- Docker support for easy deployment to cloud platforms\n- Health check endpoint for container monitoring\n\n## Supported Earthquake Categories\n\nUsers can subscribe to the following earthquake notification categories:\n\n- **Significant earthquakes**: Only the most notable events (typically M6.0+ with significant impact)\n- **Magnitude 4.5+**: Moderate to large earthquakes that can be felt over wide areas\n- **Magnitude 2.5+**: Minor earthquakes that are often felt but rarely cause damage\n- **Magnitude 1.0+**: Very minor earthquakes, usually only detected by seismographs\n- **All earthquakes**: Every earthquake detected, including very small events\n\nData is sourced from the [USGS Earthquake Feeds](https://earthquake.usgs.gov/earthquakes/feed/v1.0/atom.php), which are updated every 15 minutes.\n\n## Available Commands\n\n- `/start` - Start the bot and receive instructions\n- `/subscribe` - Subscribe to earthquake notifications\n- `/unsubscribe` - Unsubscribe from earthquake notifications\n- `/status` - Check your current subscription status\n- `/latest` - Get the latest earthquakes\n- `/customize` - Customize your notification preferences\n\n## Deployment to Google Cloud Platform\n\nThis guide will help you deploy the earthquake notification bot to Google Cloud Platform (GCP).\n\n### Prerequisites\n\n1. A Google Cloud Platform account\n2. [Google Cloud SDK](https://cloud.google.com/sdk/docs/install) installed\n3. [Docker](https://docs.docker.com/get-docker/) installed\n\n### Deployment Options\n\nThere are multiple deployment options available, each with its own advantages:\n\n1. **Cloud Run (Recommended for most users)**\n   - Serverless, scales to zero when not in use (cost-effective)\n   - Easy deployment and updates\n   - Built-in health checks\n   - Use the provided `deploy-to-gcp.sh` script\n\n2. **Compute Engine**\n   - Better for consistent, long-running workloads\n   - More control over the environment\n   - Simpler persistent storage setup\n   - Use the provided `setup-compute-engine.sh` script\n\n3. **Cloud Build with Continuous Deployment**\n   - Automatic builds and deployments from GitHub\n   - Use the provided `cloudbuild.yaml` configuration\n\n### Quick Start with Cloud Run\n\n1. Update the bot token and configuration\n   ```bash\n   cp earthquake-notifier/.env.example earthquake-notifier/.env\n   # Edit the .env file with your Telegram bot token\n   ```\n\n2. Run the deployment script (after reviewing and setting your GCP project ID in the script)\n   ```bash\n   ./deploy-to-gcp.sh\n   ```\n\n### Manual Deployment Steps\n\n1. Set up environment variables\n   ```bash\n   export PROJECT_ID=\"your-gcp-project-id\"\n   export REGION=\"us-central1\"\n   ```\n\n2. Build the Docker image\n   ```bash\n   docker build -t gcr.io/${PROJECT_ID}/earthquake-bot .\n   ```\n\n3. Push to Google Container Registry\n   ```bash\n   gcloud auth configure-docker\n   docker push gcr.io/${PROJECT_ID}/earthquake-bot\n   ```\n\n4. Deploy to Cloud Run\n   ```bash\n   gcloud run deploy earthquake-bot \\\n     --image gcr.io/${PROJECT_ID}/earthquake-bot \\\n     --platform managed \\\n     --region ${REGION} \\\n     --allow-unauthenticated \\\n     --memory 512Mi\n   ```\n\n### Setting Up a Service Account\n\nFor better security, you should create a dedicated service account:\n\n```bash\n./setup-service-account.sh\n```\n\n### Data Persistence\n\nFor persisting subscriber data when using Cloud Run:\n\n1. Create a Cloud Storage bucket\n   ```bash\n   gsutil mb -l us-central1 gs://${PROJECT_ID}-earthquake-data\n   ```\n\n2. Set up periodic sync of data to/from the bucket\n   ```bash\n   # Add these commands to your Dockerfile or as a startup script\n   gsutil cp gs://${PROJECT_ID}-earthquake-data/subscribers.json /app/data/subscribers.json || true\n   # Add a cron job to sync data back to the bucket periodically\n   ```\n\n## Local Development\n\n1. Clone the repository\n   ```bash\n   git clone https://github.com/pAulseperformance/earthquake-telegram-bot.git\n   cd earthquake-telegram-bot\n   ```\n\n2. Install dependencies\n   ```bash\n   cd earthquake-notifier\n   npm install\n   ```\n\n3. Set up environment variables\n   ```bash\n   cp .env.example .env\n   # Edit .env file with your Telegram bot token and chat ID:\n   # TELEGRAM_BOT_TOKEN=your_bot_token_here\n   # TELEGRAM_CHAT_ID=your_chat_id_here\n   # NOTIFICATION_INTERVAL=15  # Minutes between checks\n   ```\n\n4. Build TypeScript files\n   ```bash\n   npm run build\n   ```\n\n5. Start the bot\n   ```bash\n   npm start\n   ```\n\n6. Development mode with auto-reloading (alternative to steps 4-5)\n   ```bash\n   npm run dev\n   ```\n\n7. Access the health endpoint\n   ```\n   http://localhost:8080/health\n   ```\n\n### Interacting with the Bot\n\nOnce your bot is running, you can interact with it through Telegram:\n\n1. Open Telegram and search for your bot by username\n2. Start a conversation with `/start`\n3. Subscribe to earthquake notifications with `/subscribe`\n4. Check your current subscription with `/status`\n5. Get the latest earthquakes with `/latest`\n6. Customize notification preferences with `/customize`\n\n## Docker Compose for Local Testing\n\nTo test the Docker setup locally before deploying to GCP:\n\n1. Make sure Docker is installed and running on your machine\n\n2. Configure your environment variables\n   ```bash\n   cp earthquake-notifier/.env.example earthquake-notifier/.env\n   # Edit the .env file with your Telegram bot token and chat ID\n   ```\n\n3. Build and start the container\n   ```bash\n   docker-compose up --build\n   ```\n\n4. To run in detached mode (background)\n   ```bash\n   docker-compose up --build -d\n   ```\n\n5. Check logs when running in detached mode\n   ```bash\n   docker-compose logs -f\n   ```\n\n6. Stop the container\n   ```bash\n   docker-compose down\n   ```\n\n7. Access the health endpoint\n   ```\n   http://localhost:8080/health\n   ```\n\n## Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n\n## Troubleshooting\n\n### Common Issues\n\n1. **Bot doesn't respond to commands**\n   - Verify your Telegram bot token in the `.env` file\n   - Make sure your bot is running (`npm start` shows no errors)\n   - Check if you've started a conversation with the bot on Telegram\n\n2. **Environment variables not loading**\n   - Ensure the `.env` file is in the correct location\n   - Check for syntax errors in your `.env` file\n   - Try running with explicit environment variables: `TELEGRAM_BOT_TOKEN=yourtoken npm start`\n\n3. **Error when building TypeScript files**\n   - Run `npm install` to make sure all dependencies are installed\n   - Check if TypeScript is installed (`npm list typescript`)\n   - Look for errors in your `tsconfig.json` file\n\n4. **Docker issues**\n   - Make sure Docker is running on your system\n   - Try building the image with `docker build -t earthquake-bot .`\n   - Check Docker logs for any errors\n\n### Viewing Logs\n\nLocal logs are stored in the `earthquake-notifier/logs/` directory. The most recent log file will be named with the current date (e.g., `2025-05-14.log`).\n\n## License\n\nThis project is licensed under the MIT License.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpaulseperformance%2Fearthquake-telegram-bot","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpaulseperformance%2Fearthquake-telegram-bot","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpaulseperformance%2Fearthquake-telegram-bot/lists"}