Skip to content

Commit

Permalink
Merge pull request #304 from dsgnr/fix_301
Browse files Browse the repository at this point in the history
Correct documentation for API_URL environment variable"
  • Loading branch information
dsgnr authored Feb 12, 2025
2 parents 50f570f + c79db48 commit d434a5d
Showing 1 changed file with 28 additions and 18 deletions.
46 changes: 28 additions & 18 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,6 @@

[portchecker.io](https://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.


## Table of contents:

- [Getting Started](#getting-started)
Expand All @@ -15,78 +14,87 @@
- [Contributing](#contributing)

## Getting Started

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](https://litestar.dev/).

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.

## Documentation
API routes and specification can be found at [portchecker.io/docs](https://portchecker.io/docs)

API routes and specification can be found at [portchecker.io/docs](https://portchecker.io/docs)

## Development

### Standalone

#### Web

> [!NOTE]
> Uses [Node](https://nodejs.org/) version 23 and newer. Requires [Yarn](https://classic.yarnpkg.com/en/)
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](http://0.0.0.0:8080).

#### API

> [!NOTE]
> Uses Python 3.12. The Python environment uses [Poetry](https://pypi.org/project/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](http://0.0.0.0:8000).


### Docker
~~~

```
$ docker-compose -f docker-compose-dev.yml up --build
~~~
```

portchecker.io front-end will be running at [http://0.0.0.0:8080](http://0.0.0.0:8080) and the API will be running at [http://0.0.0.0:8000](http://0.0.0.0:8000).

## Production

### Docker

> [!NOTE]
> Uses [ghcr.io/dsgnr/portcheckerio-web:latest](https://github.com/dsgnr/portchecker.io/pkgs/container/portcheckerio-web) and [ghcr.io/dsgnr/portcheckerio-api:latest](https://github.com/dsgnr/portchecker.io/pkgs/container/portcheckerio-api).
~~~
```
$ docker-compose up
~~~
```

portchecker.io front-end will be running at [http://0.0.0.0:8080](http://0.0.0.0:8080) and the API will be running at [http://0.0.0.0:8000](http://0.0.0.0:8000).

## Environment Variables

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.

### Web

| Name | Required? | Default | Notes |
|------------------|-----------|-----------------|------------------------------------------------------------------------------------------|
| DEFAULT_PORT | No | http://api:8000 | The URL of the API service if changed from the default. The scheme and port is required. |
| ---------------- | --------- | --------------- | ---------------------------------------------------------------------------------------- |
| API_URL | No | http://api:8000 | The URL of the API service if changed from the default. The scheme and port is required. |
| 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 |

### API
| Name | Required? | Default | Notes |
|---------------|-----------|---------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| ALLOW_PRIVATE | No | False | Allows private IP addresses in [ IANA IPv4 Special Registry ]( https://www.iana.org/assignments/iana-ipv4-special-registry/iana-ipv4-special-registry.xhtml ) ranges to be checked |

| Name | Required? | Default | Notes |
| ------------- | --------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| ALLOW_PRIVATE | No | False | Allows private IP addresses in [ IANA IPv4 Special Registry ](https://www.iana.org/assignments/iana-ipv4-special-registry/iana-ipv4-special-registry.xhtml) ranges to be checked |

## Contributing

Expand All @@ -95,10 +103,12 @@ I'm thrilled that you’re interested in contributing to this project! Here’s
### How to Contribute

1. **Submit Issues**:

- If you encounter any bugs or have suggestions for improvements, please submit an issue on our [GitHub Issues](https://github.com/dsgnr/portchecker.io/issues) page.
- Provide as much detail as possible, including steps to reproduce and screenshots if applicable.

2. **Propose Features**:

- Have a great idea for a new feature? Open a feature request issue in the same [GitHub Issues](https://github.com/dsgnr/portchecker.io/issues) page.
- Describe the feature in detail and explain how it will benefit the project.

Expand All @@ -122,8 +132,8 @@ Where this project has been mentioned.

## Author

* Website: https://danielhand.io
* Github: [@dsgnr](https://github.com/dsgnr)
- Website: https://danielhand.io
- Github: [@dsgnr](https://github.com/dsgnr)

## Show your support

Expand Down

0 comments on commit d434a5d

Please sign in to comment.