{"id":36676101,"url":"https://github.com/tryethernal/ethernal","last_synced_at":"2026-05-25T02:10:32.438Z","repository":{"id":38308222,"uuid":"332254867","full_name":"tryethernal/ethernal","owner":"tryethernal","description":"Ethernal is a block explorer for EVM-based chains. In a few seconds, spin up a fully-featured explorer for your L1/L2 rollup/testnet. Compatible with Optimism, ZK, Anvil, Hardhat, Geth...","archived":false,"fork":false,"pushed_at":"2026-02-27T23:19:20.000Z","size":18470,"stargazers_count":261,"open_issues_count":5,"forks_count":68,"subscribers_count":1,"default_branch":"develop","last_synced_at":"2026-02-28T03:30:46.270Z","etag":null,"topics":["anvil","block-explorer","blockchain","evm","geth","hardhat","rollup","zk"],"latest_commit_sha":null,"homepage":"https://www.tryethernal.com","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tryethernal.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":"FUNDING.json","license":"LICENSE","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,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{}},"created_at":"2021-01-23T16:25:22.000Z","updated_at":"2026-02-27T22:30:48.000Z","dependencies_parsed_at":"2026-01-12T12:02:08.992Z","dependency_job_id":null,"html_url":"https://github.com/tryethernal/ethernal","commit_stats":null,"previous_names":[],"tags_count":1730,"template":false,"template_full_name":null,"purl":"pkg:github/tryethernal/ethernal","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tryethernal%2Fethernal","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tryethernal%2Fethernal/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tryethernal%2Fethernal/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tryethernal%2Fethernal/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tryethernal","download_url":"https://codeload.github.com/tryethernal/ethernal/tar.gz/refs/heads/develop","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tryethernal%2Fethernal/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30053980,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-03T17:46:22.538Z","status":"ssl_error","status_checked_at":"2026-03-03T17:46:22.036Z","response_time":61,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":["anvil","block-explorer","blockchain","evm","geth","hardhat","rollup","zk"],"created_at":"2026-01-12T10:49:27.944Z","updated_at":"2026-03-17T02:10:58.131Z","avatar_url":"https://github.com/tryethernal.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":" # Ethernal\n\n**Ethernal** is a powerful, open-source block explorer for EVM-based chains. Effortlessly explore, search, and analyze blockchain data—whether you use our hosted service or run your own private instance.\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)\n\n---\n\n## 🚀 Quick Start\n\n### Hosted Version\n\n- **Try Ethernal instantly:** [app.tryethernal.com](https://app.tryethernal.com)\n- **Create a demo explorer:** [app.tryethernal.com/demo](https://app.tryethernal.com/demo)\n\n---\n\n## 🏠 Self-Hosting Ethernal\n\n\u003e ⚠️ **Beta Notice:**\n\u003e \n\u003e The self-hosted version of Ethernal is currently in **beta**. Some features may not work as expected or may be incomplete. If you encounter any issues, please consider [opening an issue](https://github.com/tryethernal/ethernal/issues) to help us improve the project. Your feedback is greatly appreciated!\n\nRun your own Ethernal instance on your infrastructure, with full control over your data and configuration.\n\n### Prerequisites\n\n- [Docker](https://www.docker.com/) \u0026 [Docker Compose](https://docs.docker.com/compose/)\n- [OpenSSL](https://www.openssl.org/) (for environment file generation)\n- A domain name or server IP\n\n\u003e **Database:** Ethernal uses PostgreSQL (TimescaleDB) as its database backend. This is automatically provided through Docker containers—no manual installation required.\n\n### 1. Clone the Repository\n\n```bash\ngit clone https://github.com/tryethernal/ethernal.git\ncd ethernal\ngit checkout $(git describe --tags --abbrev=0) # Makes sure that you are using the latest stable version \n```\n\n### 2. Start Ethernal (Automatic Setup)\n\nJust run:\n\n```bash\nmake start\n```\n\n- On first run, this will prompt you for your domain/IP and port, then generate all secrets and config files using `generate-env-files.sh`.\n- On subsequent runs, it will skip generation and simply start the services.\n- If you ever want to regenerate your environment/config files, you can run `bash ./generate-env-files.sh` manually.\n\n\u003e **Tip:** All generated secrets and config files are automatically added to `.gitignore` for your safety.\n\n### 3. Access Your Instance\n\nAfter setup, you'll see a summary like:\n\n```\n==================== Ethernal Installation Complete! ====================\n\n🌐  DNS Setup Reminder:\n    Make sure to add an A record in your DNS provider:\n    your-domain.com -\u003e \u003cyour-server-ip-address\u003e\n\n🔗  Start here to setup your instance:\n    http://your-domain-or-ip/setup\n\n🐘  PostgreSQL Connection String:\n    postgresql://\u003cuser\u003e:\u003cpassword\u003e@\u003chost\u003e:\u003cport\u003e/\u003cdb\u003e\n\n📊  Bullboard Access (background jobs):\n    http://your-domain-or-ip/bull\n    Username: ethernal\n    Password: \u003cauto-generated\u003e\n=======================================================================\n```\n\n**👉 Next step:**\n\n- Open the setup link shown above in your browser.\n- This guided setup will help you **create your admin user account** and **set up your first explorer** quickly and easily.\n- Once complete, you'll be ready to start using Ethernal!\n\n\u003e **🌐 DNS Setup Reminder:**\n\u003e \n\u003e If you are using a custom domain (not an IP address), make sure to add an **A record** in your DNS provider:\n\u003e \n\u003e     your-domain.com -\u003e \u003cyour-server-ip-address\u003e\n\u003e \n\u003e Replace `\u003cyour-server-ip-address\u003e` with the actual public IP of your server. This is required for your domain to resolve correctly to your Ethernal instance.\n\n---\n\n## 📖 Documentation\n\nFull documentation is available at [doc.tryethernal.com](https://doc.tryethernal.com).\n\n---\n\n## 📡 API\n\nEthernal exposes a powerful API for programmatic access to your blockchain data and explorer features.\n\n- **API Documentation:**\n  - Full list of endpoints and usage examples: [Ethernal API Reference](https://documenter.getpostman.com/view/12141908/2s83zfQ5Tf)\n  - **Note:** Replace all instances of `api.tryethernal.com` in the documentation with your own server's domain or IP address.\n\nYou can use this API to:\n- Query blocks, transactions, contracts, logs, and more\n- Integrate Ethernal data into your own dashboards or tools\n- Automate explorer management (add/delete explorer, customise them, etc...)\n\nIf you need additional endpoints or have suggestions for improvements, **pull requests and issues are welcome!**\n\n---\n\n## 🛠️ Useful Makefile Commands\n\n- `make start` – Start or restart Ethernal (with env/config generation)\n- `make stop` – Stop and clean up all containers and networks\n- `make update` – Pull latest images and apply migrations/seeds\n- `make nuke` – Remove all containers, volumes, and generated config files (all data will be lost)\n- `make info` – Display connection details and setup URLs\n\n---\n\n## ⚙️ Configuration\n\n**All configuration files and environment variables are generated automatically during setup. For a default installation, you should not need to change any of these values.**\nIf you want to customize advanced settings, you can edit the relevant files after the initial setup.\n\nBelow are the main configuration files and the variables they contain:\n\n---\n\n### Backend Environment Variables (`run/.env.prod`)\n\n| Variable           | Description                        | Default     |\n|--------------------|------------------------------------|-------------|\n| ENCRYPTION_KEY     | Key used for data encryption       | -           |\n| ENCRYPTION_JWT_SECRET | Secret for JWT token encryption | -           |\n| SECRET             | Application secret key             | -           |\n| CORS_DOMAIN        | CORS allowed domains               | *           |\n| NODE_ENV           | Node environment                   | production  |\n| REDIS_URL          | Redis connection string            | redis://redis:6379 |\n| DB_USER            | PostgreSQL username                | postgres    |\n| DB_PASSWORD        | PostgreSQL password                | (random)    |\n| DB_NAME            | PostgreSQL database name           | ethernal    |\n| DB_HOST            | PostgreSQL host (via pgbouncer)    | pgbouncer   |\n| DB_PORT            | PostgreSQL port (via pgbouncer)    | 5433        |\n| SOKETI_DEFAULT_APP_ID | Soketi app id                   | default-app |\n| SOKETI_DEFAULT_APP_KEY| Soketi app key                  | app-key     |\n| SOKETI_DEFAULT_APP_SECRET| Soketi app secret            | (random)    |\n| SOKETI_HOST        | Soketi host                        | soketi      |\n| SOKETI_PORT        | Soketi port                        | 6001        |\n| PM2_HOST           | PM2 dashboard host                 | pm2:9090    |\n| PM2_SECRET         | PM2 dashboard secret               | (random)    |\n| BULLBOARD_USERNAME | Username for Bull dashboard        | ethernal    |\n| BULLBOARD_PASSWORD | Password for Bull dashboard        | (random)    |\n| APP_DOMAIN         | Your domain or IP                  | (set at setup)|\n| FIREBASE_SIGNER_KEY| Firebase signer key                | (random)    |\n| FIREBASE_SALT_SEPARATOR| Firebase salt separator        | (random)    |\n| FIREBASE_ROUNDS    | Firebase rounds                    | 8           |\n| FIREBASE_MEM_COST  | Firebase memory cost               | 14          |\n| APP_URL            | Application URL                    | (set at setup)|\n| SELF_HOSTED        | Self-hosted flag                   | true        |\n| PORT               | Application port                   | 8888        |\n| DEFAULT_PLAN_SLUG  | Default plan slug                  | self-hosted |\n\n---\n\n### PM2 Environment Variables (`pm2-server/.env.prod`)\n\n| Variable           | Description                        | Default     |\n|--------------------|------------------------------------|-------------|\n| SECRET             | PM2 dashboard secret               | (random)    |\n| ETHERNAL_SECRET    | Backend secret                     | (random)    |\n| PORT               | PM2 dashboard port                 | 9090        |\n| ETHERNAL_REDIS_URL | Redis connection string            | redis://redis:6379/0 |\n| ETHERNAL_HOST      | Backend host URL                   | http://backend:8888  |\n\n---\n\n### PostgreSQL Environment Variables (`.env.postgres.prod`)\n\n| Variable           | Description                        | Default     |\n|--------------------|------------------------------------|-------------|\n| POSTGRES_HOST      | PostgreSQL host                    | postgres    |\n| POSTGRES_USER      | PostgreSQL username                | postgres    |\n| POSTGRES_PASSWORD  | PostgreSQL password                | (random)    |\n| POSTGRES_DB        | PostgreSQL database name           | ethernal    |\n| POSTGRES_PORT      | PostgreSQL port                    | 5432        |\n\n---\n\n### Soketi Environment Variables (`.env.soketi.prod`)\n\n| Variable                   | Description                        | Default     |\n|----------------------------|------------------------------------|-------------|\n| SOKETI_DEFAULT_APP_ID      | Soketi app id                      | default-app |\n| SOKETI_DEFAULT_APP_KEY     | Soketi app key                     | app-key     |\n| SOKETI_DEFAULT_APP_SECRET  | Soketi app secret                  | (random)    |\n| SOKETI_HOST                | Soketi host                        | 0.0.0.0     |\n| SOKETI_PORT                | Soketi port                        | 6001        |\n\n---\n\n### Docker Compose Environment Variables (`.env.docker-compose.prod`)\n\n| Variable           | Description                        | Default     |\n|--------------------|------------------------------------|-------------|\n| EXPOSED_PORT       | Public HTTP port                   | 80 (or as set at setup) |\n| EXPOSED_SSL_PORT   | Public HTTPS port                  | 443 (or as set at setup) |\n\n---\n\n**Note:**\n- All secrets and passwords are generated randomly for each installation.\n- For most users, there is no need to change these values after setup.\n- The production Docker Compose file is `docker-compose.prod.yml`. You should run it with the environment file like this:\n  \n  ```bash\n  docker compose -f docker-compose.prod.yml --env-file .env.docker-compose.prod up -d\n  ```\n\n---\n\n## 📝 Blog Pipeline\n\nEthernal's blog ([tryethernal.com/blog](https://tryethernal.com/blog)) is powered by an automated trend-scanning pipeline that discovers what's happening in the Ethereum ecosystem and produces draft articles.\n\n### How it works\n\n```\nSources (EIPs, ERCs, ethresear.ch, Magicians, arxiv)\n  ↓  weekly scan\nClassify into 12 topic clusters\n  ↓\nScore by weighted signals (ERC count, research posts, arxiv papers, Google Trends)\n  ↓\nCreate draft cards on GitHub Project board\n  ↓  every 2 days\nRound-robin picker selects highest-scoring topic (skips clusters with active work)\n  ↓\nClaude CLI researches sources and drafts the article\n  ↓\nArticle committed to develop with status: draft (invisible on site, deployed for preview)\n  ↓  card link added to project board\nMove card to \"Published\" in GitHub Project\n  ↓  triggers workflow\nFrontmatter updated to status: published → article goes live on next deploy\n```\n\n**Board columns:** Detected → Researched → Drafting → Published\n\n### Running the pipeline\n\n```bash\ncd blog/pipeline\nnpm ci\n\n# Scan sources and create/update project cards\nnode index.js\n\n# Preview without creating cards\nnode index.js --dry-run\n\n# Pick next topic for drafting\nnode index.js --pick --dry-run\n```\n\n### Automation\n\n| Trigger | What | Where |\n|---------|------|-------|\n| Weekly (Mon 6am UTC) | Scan sources, update scores | `.github/workflows/blog-trend-scan.yml` |\n| Every 2 days (8am UTC) | Pick topic, research, draft to develop | `.github/workflows/blog-draft.yml` |\n| Card → Published | Update frontmatter `status: published` | `.github/workflows/blog-publish.yml` |\n| Systemd timer (Hetzner) | Same as draft workflow via Claude CLI | `blog/pipeline/draft.sh` |\n\n---\n\n## 🐞 Bug Reports\n\nFound a bug? Please [open an issue](https://github.com/tryethernal/ethernal/issues) in this repo.\n\n---\n\n## 💖 Support Us\n\nSupport Ethernal's development by subscribing to [a paid plan](https://www.tryethernal.com/pricing).\n\n**Note:** The self-hosted version will display ads by default. Running these ads helps support ongoing development of Ethernal. Thank you for contributing to the project by keeping them enabled!\n\n---\n\n## 📬 Contact Us\n\nWe'd love to hear from you!\n\n- **Twitter:** [@tryethernal](https://twitter.com/tryethernal)\n- **Discord:** [Join our community](https://discord.gg/jYCER6Mh)\n- **Email:** contact@tryethernal.com\n\n---\n\n**Happy exploring! 🚀**\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftryethernal%2Fethernal","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftryethernal%2Fethernal","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftryethernal%2Fethernal/lists"}