Skip to content

Commit 63f578c

Browse files
pbogrepbogre
committed
Improve and simplify documentation (#23)
1 parent b9ebe06 commit 63f578c

File tree

3 files changed

+61
-115
lines changed

3 files changed

+61
-115
lines changed

‎CONTRIBUTING.md

+20
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
# Contributing
2+
3+
## Pull Requests
4+
5+
I am more than happy to review pull requests for features or bug fixes.
6+
If your pull request involves a large change in Jetlog, please open an
7+
issue about it before you spend a lot of time working on it.
8+
9+
## Bugs
10+
11+
If you spot erroneous behavior in Jetlog, feel free to open an issue about it.
12+
Please make sure that you include any relevant information like logs, screenshots, etc.
13+
14+
## Features
15+
16+
If there is a feature that you would like to see added, make sure that someone has
17+
not requested it before (and if someone did, leave a thumbs up on that issue so I can track
18+
interest). Also please describe your use case for that feature, and be wary that I
19+
would like to keep Jetlog focused on its function, so I may reject feature requests
20+
that I deem to go out of the scope of the project.

‎README.md

+41-103
Original file line numberDiff line numberDiff line change
@@ -10,121 +10,58 @@ A self-hostable personal flight tracker and viewer
1010
![homepage preview](images/homepage.png)|![all flights preview](images/all-flights.png)
1111
:--------------------------------------:|:---------------------------------------------:
1212

13-
## Index
13+
## Table of Contents
14+
1415
- [Features](#features)
15-
- [Installation](#installation)
16-
- [Docker](#docker-recommended)
17-
- [Manual](#manual-development)
18-
- [Importing](#importing)
19-
- [MyFlightRadar24](#myflightradar24)
20-
- [Custom](#custom-csv)
21-
- [API](#api-documentation)
16+
- [Getting Started](#getting-started)
17+
- [Importing & Exporting](#importing--exporting)
2218
- [Stack](#stack)
2319
- [Other credits](#other-credits)
2420

2521
## Features
2622

27-
- 🌍 World map view of all visited airports and trajectories of flights
23+
- 🌍 World map view of all your flights
2824
- 📊 Statistics for all your flights
2925
- 📱 Responsive design
30-
- 👨‍💻 Sleek and intuitive UI
31-
- ✅ Effortlessly add, edit, and delete past flights
32-
- 💾 Ability to import from CSV, MyFlightRadar24
33-
- 💾 Ability to export to CSV, iCal
34-
35-
## Installation
36-
37-
### Docker (recommended)
38-
39-
Use the sample `docker-compose.yml` from the repo or make your own.
40-
Make sure to add a volume from your data path to `/data`, and remember that the application in the container runs on port `3000`.
41-
42-
**Note**: Please make sure that the volume you are binding to the container has appropriate ownership, otherwise it won't start.
43-
To do this, you can either create the folder to be used as volume before running the container for the first time, or let docker
44-
create it first and then set its ownership manually by running `sudo chown -R 1000:1000 /path/to/volume/folder` (you can change
45-
`1000:1000` to whatever your user and group IDs are).
46-
47-
**Non-stable releases**: You can pull the image with the `:experimental` tag to gain access to the latest features which have not been thoroughly tested yet.
48-
49-
**Supported platforms**: `linux/amd64`, `linux/arm64`.
50-
51-
Below are some of the environment variables you can set in the Docker Compose.
52-
53-
| Name | Default | Function |
54-
|---------------|---------|---------------------|
55-
| `APP_PATH` | `/app` | App path |
56-
| `DATA_PATH` | `/data` | Data path |
57-
| `PGID` | `1000` | Group ID for Jetlog |
58-
| `PUID` | `1000` | User ID for Jetlog |
59-
| `JETLOG_PORT` | `3000` | HTTP Port |
60-
61-
### Manual (development)
62-
63-
1. Clone the repository and `cd` to it
64-
2. Install npm dependencies and build frontend
65-
```
66-
npm ci
67-
npm run build
68-
```
69-
3. Install pipfile dependencies with pipenv
70-
```
71-
pip install pipenv
72-
pipenv install
73-
```
74-
4. Open the virtual shell and start the server
75-
```
76-
pipenv shell
77-
(jetlog) python -m uvicorn main:app --app-dir server --host 0.0.0.0 --port 3000
78-
```
79-
5. All done, you can open `http://localhost:3000` on your browser to view jetlog
80-
81-
## Importing
82-
83-
The API has a dedicated `/importing` endpoint, which supports the formats described below
84-
85-
### MyFlightRadar24
86-
87-
1. Go to `MyFlightRadar24 > Settings > Export` and download the CSV
88-
2. Go to `Jetlog > Settings > Import`
89-
3. Upload your CSV in the `MyFlightRadar24` section and press `Import`
90-
4. Check your logs for progress
91-
92-
### Custom CSV
93-
94-
This format allows you to create a custom CSV that will be imported.
95-
The CSV should have the following columns (order doesn't matter):
96-
97-
|Column name |Required|Format|
98-
|----------------|--------|-----------|
99-
|`date` | `Yes` |`YYYY-MM-DD`|
100-
|`origin` | `Yes` |ICAO code of origin airport (4 letters)|
101-
|`destination` | `Yes` |ICAO code of destination airport (4 letters)|
102-
|`departure_time`| `No` |`HH:MM`|
103-
|`arrival_time` | `No` |`HH:MM`|
104-
|`arrival_date` | `No` |`YYYY-MM-DD`|
105-
|`seat` | `No` |One of `window`,`middle`,`aisle`|
106-
|`duration` | `No` |Number of minutes (integer)|
107-
|`distance` | `No` |Kilometers (integer) (not miles!)|
108-
|`airplane` | `No` |String|
109-
|`flight_number` | `No` |String|
110-
|`notes` | `No` |String|
111-
112-
The importing logs should give you information about any errors.
113-
114-
Here's an example custom CSV:
115-
```csv
116-
date,distance,origin,destination,arrival_time,departure_time
117-
2024-03-14,800,lime,eheh,11:20,10:00
118-
2024-03-19,800,eheh,lime,18:40,16:30
26+
- ✅ Add, edit, and delete past flights
27+
- 💾 Ability to import and export your data
28+
29+
Visit the [usage wiki](https://github.com/pbogre/jetlog/wiki/Usage) for details on all the features of Jetlog
30+
31+
## Getting Started
32+
33+
Here's a sample `docker-compose.yml` to get started
34+
```yml
35+
services:
36+
jetlog:
37+
image: pbogre/jetlog:latest
38+
volumes:
39+
- /your/data/path:/data
40+
restart: unless-stopped
41+
ports:
42+
- 3000:3000
11943
```
12044
121-
1. Go to `Jetlog > Settings > Import`
122-
2. Upload your CSV in the `Custom CSV` section and press `Import`
123-
3. Check your logs for progress
45+
For details about troubleshooting, environment variables, and more installation options, have a look at the [installation wiki](https://github.com/pbogre/jetlog/wiki/Installation)
46+
47+
## Importing & Exporting
48+
49+
You can currently import from the following formats
50+
51+
- MyFlightRadar24
52+
- Custom CSV
12453
125-
## API documentation
54+
You can currently export to the following formats
12655
127-
You can make use of the automatically generated docs (thanks to FastAPI) by going to `http://<your-ip>:<your-port>/docs`.
56+
- CSV
57+
- iCal
58+
59+
For details on how to import your data, have a look at the [importing wiki](https://github.com/pbogre/jetlog/wiki/Importing)
60+
61+
## Contributing
62+
63+
If you would like to contribute to this project by opening an issue or a pull request,
64+
please read [CONTRIBUTING.md](https://github.com/pbogre/jetlog/blob/main/CONTRIBUTING.md)
12865
12966
## Stack
13067
@@ -139,3 +76,4 @@ You can make use of the automatically generated docs (thanks to FastAPI) by goin
13976
- [Airports database](https://github.com/jpatokal/openflights/)
14077
- [react-simple-map](https://www.react-simple-maps.io/)
14178
- [World GeoJSON](https://geojson-maps.kyd.au/)
79+

‎docker-compose.yml

-12
This file was deleted.

0 commit comments

Comments
 (0)