Skip to content

Commit

Permalink
chore: readme makes much more sense, and is up to date
Browse files Browse the repository at this point in the history
  • Loading branch information
fwuffyboi committed Mar 17, 2024
1 parent 8e34159 commit a9475a5
Show file tree
Hide file tree
Showing 10 changed files with 41 additions and 28 deletions.
69 changes: 41 additions & 28 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -17,35 +17,37 @@ This application is designed to be used on a linux server, however it may also b
### Installation
To install Peek, you will need to have Go installed on your system. If you do not have Go installed, you can download it from [here](https://golang.org/dl/) (https://golang.org/dl).

Once you have Go installed, you can install Peek by running this command:
```bash
git clone --branch v0.8.8-alpha https://github.com/fwuffyboi/peek.git # Clone the repo
cd peek/src # Go into the necessary directory
go build -o peek . # Build the file
sudo chmod +x peek # Make the file executable
sudo mv peek /usr/local/bin/peek # Move the file to /usr/local/bin
cd ../.. # Get out of the directory
sudo rm -rf peek # Delete the unnecessary repo
```
Once installed, if you are reading this on GitHub, please look to the right of your screen and look at the name of the latest release. If you are _not_ reading this on GitHub, please go to the [releases page](https://github.com/fwuffyboi/peek/releases) and copy the name of the latest release. If you are confused, please see the below image:

Then just run the command `peek` in your terminal to start. You can now access the server at its default port of `http://0.0.0.0:42649`.
![GitHub releases page for Peek](/src/assets/readme/ss-release.png)

⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️
In the case of the above image, the latest release is titled "v0.8.8-alpha".
When you have this, you can run the following commands to install Peek. Replace "RELEASE_NAME" with the name of the latest release.

**WARNING: Currently, Peek does not have any authentication. This means that anyone on your server's local network can access the server's API, and they _WILL_ be able to access _ALL_ statistics and endpoints that are enabled in the configuration file. However, the default configuration is considered to be a "Safe default", allowing anyone on the local network to _ONLY_ view the logs of Peek (This is not sensitive information) or be able to see system information EXCEPT the server's public IP address. No actions (such as shutting the server down, or stopping peek) can be taken from the API on these defaults.**
```bash
git clone --branch RELEASE_NAME https://github.com/fwuffyboi/peek.git # Clone the repo
cd peek/src # Go into the necessary directories
go build -o peek . # Build the application, (should only take a minute at most)
sudo chmod +x peek # Make sure that the file is executable
sudo mv peek /usr/local/bin/peek # Move the file to /usr/local/bin, for local user installation
cd ../.. # Leave both directories
sudo rm -rf peek # Delete the now-unnecessary repo
```

⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️
Then just run the command `peek` in your terminal to start. You can now access the server at its default port of `http://0.0.0.0:42649`.


### How to configure

To configure Peek, you must first run the application after moving it to /usr/local/bin/peek. This will create a default configuration in /home/{YOUR_USERNAME}/.config/peek called peek.config.yaml. It is recommended to stop the Peek application before editing this, as that can lead to unsaved changes. Once edited, start Peek again and it will load your new configuration. If there is an issue with it not working, please feel free to create a GitHub issue.


### Log file

The name of the log file in the Peek configuration file is what the log file will be called.
The log file's location will remain in `/home/YOUR_USERNAME/.config/peek/`. This only changes the file's name. Nothing else. The default log file value is "peek.log".


### Logging level

Peek allows you to choose what level of logging you would prefer.
Expand All @@ -55,6 +57,7 @@ There are also the other options: WARN, ERR and FATA.

WARN only shows warnings in the program, and isn't very helpful. ERR only shows errors, and FATA only shows what caused a program to stop running. It is highly recommended to stick to the default. As this shows information that is critically helpful during debugging.


### How to uninstall

Run these commands after stopping the Peek application:
Expand All @@ -67,27 +70,37 @@ sudo rm -rf /home/{YOUR_USERNAME}/.config/peek
```


### Screenshots (From v0.8.7-alpha)
![Screenshot](/src/assets/readme/ss-api-full.png)
URL: `/api/stats/all`
### Screenshots (From v0.10.0-alpha)
Some screenshots of the API in action.

Since the last update, the API has been completely rewritten to be more user-friendly and easier to understand. A basic authentication system has also been put into place.

![ss-api-stats-all-auth](/src/assets/readme/ss-api-stats-all-auth.png)

URL: `/api/v1/stats/all`

The above screenshot shows what this endpoint responds with, under authenticated users. Below is what unauthenticated users would see.

![ss-api-stats-all-unauth](/src/assets/readme/ss-api-stats-all-unauth.png)

When I request the `/api/v1/stats/all/` endpoint from my cell phone, Peek on my server reports a varying response time of between `4ms to 6.5ms`


Peek has a new endpoint that allows you to see "alerts" for your installation. Currently, alerts only consist of update reminders. This is a screenshot of the alerts endpoint.
![ss-api-peek-alerts-auth](/src/assets/readme/ss-api-peek-alerts-auth.png)

The above screenshot shows the full API response from the server.
This is the most detailed response you can get from the API. Below is shown an example of what peek would log for this request.
I request the /api/stats/all endpoint from my Pixel 6a device on IP 192.168.0.57, to my server at 192.168.0.80. The server's hostname is fedorable.

`{"clientIP":"192.168.0.57","dataLength":716,"hostname":"fedorable","latency":4,"level":"info","method":"GET","msg":"192.168.0.57 - fedorable [17/Feb/2024:10:22:08 +0000] \"GET /api/stats/all/\" 200 716 \"\" \"Mozilla/5.0 (Android 14; Mobile; rv:122.0) Gecko/122.0 Firefox/122.0\" (4ms)","path":"/api/full/","referer":"","statusCode":200,"time":"2024-02-17T10:22:08Z","userAgent":"Mozilla/5.0 (Android 14; Mobile; rv:122.0) Gecko/122.0 Firefox/122.0"}`
Recently, the API has been updated to allow the use of a built-in rate limiter. As well as a swagger UI for the API.

This request took 4ms(precisely 4.029865ms) total to complete. This includes getting all the data, reverse geolocating the IP, etc., and sending the response back to the client.
![ss-api-swagger](/src/assets/readme/ss-api-swagger.png)

![Screenshot](/src/assets/readme/ss-api-endpoints.png)
URL: `/api/`
URL: `/api/swagger/index.html`

The above screenshot shows the API endpoints available to the client.
The rate limiter is, by default, set to 5 requests per second, but this is easily customizable in the config file. This is the response when the rate limit is exceeded.

![Screenshot](/src/assets/readme/ss-api-index.png)
URL: `/`
![ss-api-ratelimit](/src/assets/readme/ss-api-ratelimit.png)

The above screenshot shows the index page of the API.
URL: `Any! (Except swagger/*)`


### Credits/Contributors
Expand Down
Binary file removed src/assets/readme/ss-api-endpoints.png
Binary file not shown.
Binary file removed src/assets/readme/ss-api-full.png
Binary file not shown.
Binary file removed src/assets/readme/ss-api-index.png
Binary file not shown.
Binary file added src/assets/readme/ss-api-peek-alerts-auth.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added src/assets/readme/ss-api-ratelimit.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added src/assets/readme/ss-api-stats-all-auth.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added src/assets/readme/ss-api-stats-all-unauth.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added src/assets/readme/ss-api-swagger.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added src/assets/readme/ss-release.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.

0 comments on commit a9475a5

Please sign in to comment.