portchecker.io is an open-source API for checking port availability on specified hostnames or IP addresses. Ideal for developers and network admins, it helps troubleshoot network setups, validate firewall rules, and assess potential access points.
The project consists of two containers. The front-end is a static HTML file sat behind Nginx. The back-end is a simple API built using Litestar.
The project aims to be super simple, with low overhead and also the least amount of dependencies as possible.
The project contains both production and development stacks. The production stack utilises gunicorn as the API's process manager with uvicorn workers. Development utilises uvicorn with the --reload parameter.
API routes and specification can be found at portchecker.io/docs
Bringing up the UI outside of Docker;
$ cd frontend/web
$ yarn install
$ yarn dev
portchecker.io front-end be running at http://0.0.0.0:8080.
Note
Uses Python 3.12. The Python environment uses Poetry for package management. This must be installed.
$ cd backend/api
$ poetry install
$ uvicorn main:app --host 0.0.0.0 --port 8000 --reload
portchecker.io API be running at http://0.0.0.0:8000.
$ docker-compose -f docker-compose-dev.yml up --build
portchecker.io front-end will be running at http://0.0.0.0:8080 and the API will be running at http://0.0.0.0:8000.
$ docker-compose up
portchecker.io front-end will be running at http://0.0.0.0:8080 and the API will be running at http://0.0.0.0:8000.
The following configuration options are available. These would be set within the Docker compose files, or in your environment if you're using portchecker standalone.
| Name | Required? | Default | Notes |
|---|---|---|---|
| DEFAULT_PORT | No | 443 | Allows a default port number to be prefilled in the UI |
| GOOGLE_ANALYTICS | No | Allows for a Google Analytics tracking code to be provided |
| Name | Required? | Default | Notes |
|---|---|---|---|
| ALLOW_PRIVATE | No | False | Allows private IP addresses in IANA IPv4 Special Registry ranges to be checked |
I'm thrilled that you’re interested in contributing to this project! Here’s how you can get involved:
-
Submit Issues:
- If you encounter any bugs or have suggestions for improvements, please submit an issue on our GitHub Issues page.
- Provide as much detail as possible, including steps to reproduce and screenshots if applicable.
-
Propose Features:
- Have a great idea for a new feature? Open a feature request issue in the same GitHub Issues page.
- Describe the feature in detail and explain how it will benefit the project.
-
Submit Pull Requests:
- Fork the repository and create a new branch for your changes.
- Make your modifications and test thoroughly.
- Open a pull request against the
develbranch of the original repository. Include a clear description of your changes and any relevant context.
Where this project has been mentioned.
DB Tech - PortChecker - Check for Open Ports EASILY (Docker Tutorial)
SYNACK Time - Portchecker.io Tutorial: Open Source Scanner with API Integration & Self-Hosting
selfh.st - This Week in Self-Hosted (8 November 2024)
- Website: https://danielhand.io
- Github: @dsgnr
Give a ⭐️ if this project helped you!
Running websites such as this comes with associated costs. Any donations to help the running of the site is hugely appreciated!
The site is located on Digital Ocean. You can use the following referral link to get some credit when joining:
See the LICENSE file for more details on terms and conditions.
