Skip to content

Commit 2a957c8

Browse files
d-hpd-hp
committed
docketeer x README.md
1 parent 3fe2441 commit 2a957c8

File tree

3 files changed

+178
-137
lines changed

3 files changed

+178
-137
lines changed

‎README.md‎

Lines changed: 178 additions & 137 deletions
Original file line numberDiff line numberDiff line change
@@ -1,190 +1,197 @@
1-
<!-- A brief description of your project, what it is used for and how does life get
2-
awesome when someone starts to use it.
3-
- Note and briefly describe any key concepts (technical, philosophical, or both) important to the user’s understanding.
4-
- Link to any supplementary blog posts or project main pages.
5-
- State if it is out-of-the-box user-friendly, so it’s clear to the user.
6-
- List its most useful/innovative/noteworthy features.
7-
- State its goals/what problem(s) it solves. -->
8-
9-
<!-- To help keep this READme organized, use two line breaks for each ## -->
10-
11-
#
12-
13-
# [Docketeer](https://www.docketeer.org/) &middot; ![Github](https://img.shields.io/github/repo-size/open-source-labs/Docketeer) ![GitHub](https://img.shields.io/github/license/open-source-labs/Docketeer) ![GitHub](https://img.shields.io/badge/PRs-welcome-orange) ![GitHub](https://img.shields.io/github/last-commit/open-source-labs/Docketeer)
1+
<!-- Improved compatibility of back to top link: See: https://github.com/othneildrew/Best-README-Template/pull/73 -->
2+
3+
<a name="readme-top"></a>
4+
5+
<!-- PROJECT SHIELDS -->
6+
<!--
7+
*** I'm using markdown "reference style" links for readability.
8+
*** Reference links are enclosed in brackets [ ] instead of parentheses ( ).
9+
*** See the bottom of this document for the declaration of the reference variables
10+
*** for contributors-url, forks-url, etc. This is an optional, concise syntax you may use.
11+
*** https://www.markdownguide.org/basic-syntax/#reference-style-links
12+
-->
13+
14+
[![Contributors][contributors-shield]][contributors-url]
15+
[![Forks][forks-shield]][forks-url]
16+
[![Stargazers][stars-shield]][stars-url]
17+
[![Issues][issues-shield]][issues-url]
18+
[![MIT License][license-shield]][license-url]
19+
[![LinkedIn][linkedin-shield]][linkedin-url]
20+
21+
<!-- PROJECT LOGO -->
22+
<br />
23+
<div align="center">
24+
<a href="https://github.com/open-source-labs/Docketeer">
25+
<img src="assets/docketeer-title.png" alt="Logo" width="325" height="auto">
26+
</a>
27+
<br />
28+
<br />
29+
<img src="assets/demo.gif" alt="Logo" width="fit" height="auto">
30+
<br />
31+
<br />
32+
<p align="center">
33+
Docketeer is a developer-friendly application that provides a single interface for both container management & metric visualization.
34+
<br />
35+
<a href="https://github.com/open-source-labs/Docketeer"><strong>Explore the docs »</strong></a>
36+
<br />
37+
<br />
38+
<a href="https://github.com/open-source-labs/Docketeer">View Demo</a>
39+
·
40+
<a href="https://github.com/open-source-labs/Docketeer/issues">Report Bug</a>
41+
·
42+
<a href="https://github.com/open-source-labs/Docketeer/issues">Request Feature</a>
43+
</p>
44+
</div>
45+
46+
<br />
47+
<!-- TABLE OF CONTENTS -->
48+
49+
<br />
1450

1551
## Table of Contents
1652

17-
- [About](#about)
18-
- [Installation](#installation)
19-
- [Features](#features)
20-
- [Testing](#testing)
21-
- [Contributing](#contributing)
22-
- [Show your support](#Show-your-support)
53+
<ol>
54+
<br />
55+
<li>
56+
<a href="#about-the-project">About Docketeer</a>
57+
<ul>
58+
<li><a href="#built-with">Built With</a></li>
59+
</ul>
60+
</li>
61+
<li>
62+
<a href="#getting-started">Getting Started</a>
63+
<ul>
64+
<li><a href="#prerequisites">Prerequisites</a></li>
65+
<li><a href="#installation">Installation</a></li>
66+
</ul>
67+
</li>
68+
<li><a href="#usage">Usage</a></li>
69+
<li><a href="#roadmap">Roadmap</a></li>
70+
<li><a href="#contributing">Contributing</a></li>
71+
<li><a href="#license">License</a></li>
72+
<li><a href="#authors">Authors</a></li>
73+
</ol>
2374

24-
#
75+
<!-- ABOUT THE PROJECT -->
76+
<br />
2577

26-
![logo](assets/docketeer-title2.png)
78+
## About The Project
2779

28-
## About
80+
<br />
81+
<div align="center">
82+
<img src="assets/finalabout.jpg" alt="Logo" width="fit" height="auto">
83+
</div>
84+
<br />
2985

30-
Managing Docker images, containers and networks from the command line while also trying to monitor crucial metrics can be tedious and counterintuitive. To make this process more developer-friendly, we created Docketeer: a container management platform for Docker.
86+
Docketeer is an open source initiative comprising contributions from dozens of talented and passionate software engineers. Our application provides a simple interface to manage Docker resources & visualize both host and container metric data. Docketeer is a containarized application that can be deployed alongside your application cluster with hardly any effort. To learn more about our application and how to get started, keep reading!
3187

32-
## Installation
88+
<p align="right">(<a href="#readme-top">back to top</a>)</p>
3389

34-
1. **Fork** and **clone** this [repository](https://github.com/open-source-labs/Docketeer.git) to your machine.
90+
### Built With
3591

36-
```
37-
git clone https://github.com/open-source-labs/Docketeer.git
38-
```
39-
40-
2. Navigate to the project directory and install dependencies.
92+
[![React][React.js]][React-url][![Typescript][TS.js]][TS-url][![Redux][Redux]][Redux-url][![Webpack][Webpack]][Webpack-url][![TailwindCSS][Tailwind]][Tailwind-url][![Node][Node.js]][Node-url][![Express][Express]][Express-url][![Grafana][Grafana]][Grafana-url][![Docker][Docker]][Docker-url]
4193

42-
```
43-
npm install
44-
```
94+
<p align="right">(<a href="#readme-top">back to top</a>)</p>
4595

46-
3. Create a `.env` file in the project's top-level directory.
96+
<!-- GETTING STARTED -->
4797

48-
```
49-
root
50-
├─ .env
51-
├─ server
52-
└─ src
53-
```
98+
## Getting Started
5499

55-
4. In the .env file, configure the following environment variables for Twilio API, Slack Webhook, and Postgres URI. Refer to [Twilio](#-Twilio) setup section below. The Postgres URI is the only field that is required, others are optional. Create your own database to house user information and insert your URI in this file.
100+
The local configuration for Docketeer was setup to be as simple as possible for the end-user. Follow the steps below to get started with Docketeer.
56101

57-
```js
58-
// .env
59-
TWILIO_NUMBER = '';
60-
TWILIO_ACCOUNT_SID = '';
61-
TWILIO_AUTH_TOKEN = '';
62-
SERVICE_SID = '';
63-
VERIFICATION_SERVICE_SID = '';
64-
SLACK_WEBHOOK = '';
65-
POSTGRES_URI = '';
66-
```
102+
<br />
67103

68-
5. Create a folder called `security` in the project's top-level directory. Inside of the `security` folder, create two files `email.js` and `sysadmin.js`. These files will store variables related to the email notification service and system admin setup respectively.
104+
#### STEP 1 — Clone the repository
69105

70-
```
71-
root
72-
├─ security
73-
├─ email.js
74-
└─ sysadmin.js
75-
├─ server
76-
└─ src
106+
```sh
107+
git clone https://github.com/open-source-labs/Docketeer.git
77108
```
78109

79-
6. In the `email.js` file, input your organization's email credentials within the username and password properties. This email address will be used to send email notifications. The file is already in the `.gitignore` file.
80-
Important: Do not change the host and port values unless you are using a different email provider.
110+
<br />
81111

82-
```js
83-
// email.js
84-
module.exports = {
85-
host: 'smtp.gmail.com',
86-
port: 465,
87-
username: '[email protected]',
88-
password: 'belugas',
89-
};
90-
```
112+
#### STEP 2 — Setup environment variables
91113

92-
7. In the `sysadmin.js` file, input information for the system admin account. If no information is input, the email and phone number for the system admin will be set to default values. These values can always be changed in the system admin's Settings tab.
114+
<p>Create a .env file at the top level of the project directory with the following contents:</p>
93115

94116
```js
95-
// sysadmin.js
96-
module.exports = {
97-
phone: '',
98-
email: '',
99-
};
100-
```
101-
102-
You are all set! Now just enter the following command to start up Docketeer!
103-
104-
```
105-
npm run dev
117+
# .env
118+
POSTGRES_PORT=5432
119+
POSTGRES_NAME=docketeer-db
120+
POSTGRES_USER=postgres
121+
POSTGRES_PASS=postgres
106122
```
107123

108-
For now, the sign up function will create a System Admin user.
124+
<br />
109125

110-
## Twilio setup
126+
#### STEP 3 — Docker compose up
111127

112-
1. Follow documents found [here](https://www.twilio.com/docs/node/install) to download the helper library.
113-
2. In order to manage Twilio SMS notifications follow the [step plan](https://www.twilio.com/docs/notify/quickstart/sms#messagingservice).
114-
3. Store your (i) Twilio number, (ii) Account Sid, (iii) Auth Token from twilio.com/console, (iv) SERVICE_SID, (v) verification service SID in a newly created .env file in the Docketeer folder in the following format:
115-
116-
```js
117-
// .env.js
118-
MY_PHONE_NUMBER = 'your mobile number';
119-
TWILIO_ACCOUNT_SID = 'code from your console';
120-
TWILIO_AUTH_TOKEN = 'token from your console';
121-
SERVICE_SID = 'code from notify service instance';
122-
VERIFICATION_SERVICE_SID = 'code from verify service instance';
128+
```sh
129+
docker compose up
123130
```
124131

125-
4. Verification service was created [here](https://www.twilio.com/console/verify/services); code length and serviceSID can be taken from your Twilio account console.
126-
5. All historical messages from the Twilio account can be found [here](https://www.twilio.com/console/sms/logs).
132+
<br />
127133

128-
<!-- > Getting started with Docketeer is easy: visit [docketeer.org](https://www.docketeer.org/) and download the Docketeer desktop app. Drag and drop the .dmg file that you downloaded into your Applications folder to install it. Before you run the application, make sure Docker itself is running. -->
134+
#### STEP 4 — Navigate to localhost:4000 to sign-up & login!
129135

130-
## Features
131-
132-
### ➮ System Wide Notifications
133-
134-
Docketeer offers monitoring support for teams by incorporating sms, email and slack notification as well as configurable options based on a container's memory or cpu usage.
135-
136-
### ➮ Viewing
136+
```sh
137+
http://localhost:4000/
138+
```
137139

138-
You can view a list of running and exited containers, available images, volume history, and docker-compose files stored locally.
140+
<p align="right">(<a href="#readme-top">back to top</a>)</p>
139141

140-
### ➮ Live Metrics
142+
<!-- USAGE EXAMPLES -->
141143

142-
Users have real-time access to the total amount of resources (CPU, memory usage) that your containers are using and total block IO bytes by image over specific time periods.
143-
![alt text](assets/metrics.gif)
144+
## Usage
144145

145-
### ➮ Uploading
146+
Coming soon...
146147

147-
Within the Image and Docker Compose tab, you pull images from DockerHub by providing `repo:version` or uploading a `.yml` file.
148+
<p align="right">(<a href="#readme-top">back to top</a>)</p>
148149

149-
### ➮ Process Logs
150+
<!-- ROADMAP -->
150151

151-
View process logs from any number of running or stopped containers. The table is both exportable and sortable by any parameter. You can filter logs by specifying the number of logs that you wish to receive (tail) as well as time (since). Process logs will help you analyze and debug problems faster by offering insights into what went wrong.
152+
## Roadmap
152153

153-
![alt text](assets/logs.gif)
154+
- [ ] Server-side integration of dockerode
155+
- [ ] Continued efforts to implement static typechecking using TypeScript throughout source code
156+
- [ ] Create additional tests to validate existing client-side & server-side functionality
157+
- [ ] Unit tests
158+
- [ ] Integration tests
159+
- [ ] End-to-end tests
154160

155-
<br> For a full demo of Docketeer's features, visit [docketeer.org](https://www.docketeer.org/demo).
161+
See the [open issues](https://github.com/github_username/repo_name/issues) for a full list of proposed features (and known issues).
156162

157-
<!-- ## Development 🛠
158-
All ideas and contributions to the project are welcome. To run the app in development mode, clone our repo to your local machine and execute the following commands:
159-
```
160-
npm run dev
161-
``` -->
163+
<p align="right">(<a href="#readme-top">back to top</a>)</p>
162164

163-
## Testing
165+
<!-- CONTRIBUTING -->
164166

165-
To conduct tests on the codebase, clone our repo to your local machine and execute the following commands in the terminal:
167+
## Contributing
166168

167-
```
168-
npm run test
169-
```
169+
Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are **greatly appreciated**.
170170

171-
## Troubleshoot
171+
If you have a suggestion that would make this better, please fork the repository and create a pull request. You can also simply open an issue describing your contribution.
172+
Don't forget to give the project a star! Thanks again!
172173

173-
#### **Cannot connect to the Docker daemon**
174+
1. Fork the Project
175+
2. Checkout Development (`git checkout development`)
176+
3. Create your Feature Branch (`git checkout -b feature/NewFeatureName`)
177+
4. Commit your Changes (`git commit -m 'Add some NewFeatureMessage'`)
178+
5. Push to the Branch (`git push origin feature/NewFeatureName`)
179+
6. Open a Pull Request (from `feature/NewFeatureName` to `development`)
180+
7. Create an issue on GitHub (as mentioned above!)
174181

175-
⤷ Make sure that you have Docker running!
182+
Read our [contributing guide](https://github.com/open-source-labs/Docketeer/blob/master/CONTRIBUTING.md) for more information on how to purpose bugfixes and improvements to Docketeer.
176183

177-
#### **Working with WSL**
184+
<p align="right">(<a href="#readme-top">back to top</a>)</p>
178185

179-
⤷ Users may need to install a third-party App to run electron. A helpful article can be found [here](https://techcommunity.microsoft.com/t5/windows-dev-appconsult/running-wsl-gui-apps-on-windows-10/ba-p/1493242).
186+
<!-- LICENSE -->
180187

181-
## Contributing
188+
## License
182189

183-
Read our [contributing guide](https://github.com/open-source-labs/Docketeer/blob/master/CONTRIBUTING.md) for more information on how to purpose bugfixes and improvements to Docketeer.
190+
Distributed under the MIT License. See `LICENSE.txt` for more information.
184191

185-
### Authors
192+
<p align="right">(<a href="#readme-top">back to top</a>)</p>
186193

187-
<!-- Most recent contributors please add your name to the BOTTOM of the list -->
194+
## Authors
188195

189196
- Dan Lin [@DanLin91](https://github.com/DanLin91) | [Linkedin](https://www.linkedin.com/in/danlin91/)
190197
- Kadir Gundogdu [@kadirgund](https://github.com/kadirgund) | [Linkedin](https://www.linkedin.com/in/kadirgund/)
@@ -227,11 +234,45 @@ Read our [contributing guide](https://github.com/open-source-labs/Docketeer/blob
227234
- Garima Bhatia [@GarimaB06](https://github.com/GarimaB06) | [LinkedIn](https://www.linkedin.com/in/garimab06/)
228235
- Nathan Cho [@nathanycho](https://github.com/nathanycho) | [LinkedIn](https://www.linkedin.com/in/nathanycho/)
229236
- Jonathan Wong [@WongJonathann](https://github.com/WongJonathann) | [LinkedIn](https://www.linkedin.com/in/jon-wong-00/)
237+
- Dillon H. Patel [@d-hp](https://github.com/d-hp)
238+
- Alex Schmidt [@RedAfronNinja](https://github.com/RedAfronNinja) | [LinkedIn](https://www.linkedin.com/in/alex-schmidt-44b27413b/)
239+
- Edward Kenny [@EdwardKenny](https://github.com/EdwardKenny) | [LinkedIn](https://www.linkedin.com/in/edward-kenny-8949b8136/)
240+
- Kennan Budnik [@kobudnik](https://github.com/kobudnik) | [LinkedIn](https://www.linkedin.com/in/kobudnik/)
230241

231-
### License
232-
233-
Docketeer is [MIT Licensed](https://github.com/open-source-labs/Docketeer/blob/master/LICENSE)
242+
<p align="right">(<a href="#readme-top">back to top</a>)</p>
234243

235244
## Show your support
236245

237246
Give a ⭐️ if this project helped you!
247+
248+
[contributors-shield]: https://img.shields.io/github/contributors/open-source-labs/Docketeer.svg?style=for-the-badge
249+
[contributors-url]: https://github.com/open-source-labs/Docketeer/graphs/contributors
250+
[forks-shield]: https://img.shields.io/github/forks/open-source-labs/Docketeer.svg?style=for-the-badge
251+
[forks-url]: https://github.com/open-source-labs/Docketeer/network/members
252+
[stars-shield]: https://img.shields.io/github/stars/open-source-labs/Docketeer.svg?style=for-the-badge
253+
[stars-url]: https://github.com/open-source-labs/Docketeer/stargazers
254+
[issues-shield]: https://img.shields.io/github/issues/open-source-labs/Docketeer.svg?style=for-the-badge
255+
[issues-url]: https://github.com/open-source-labs/Docketeer/issues
256+
[license-shield]: https://img.shields.io/github/license/open-source-labs/Docketeer.svg?style=for-the-badge
257+
[license-url]: https://github.com/open-source-labs/Docketeer/blob/master/LICENSE.txt
258+
[linkedin-shield]: https://img.shields.io/badge/-LinkedIn-black.svg?style=for-the-badge&logo=linkedin&colorB=555
259+
[linkedin-url]: https://linkedin.com/in/linkedin_username
260+
[product-screenshot]: images/screenshot.png
261+
[React.js]: https://img.shields.io/badge/React-20232A?style=for-the-badge&logo=react&logoColor=61DAFB
262+
[React-url]: https://reactjs.org/
263+
[TS.js]: https://img.shields.io/badge/TypeScript-000000?style=for-the-badge&logo=typescript&logoColor=white
264+
[TS-url]: https://www.typescriptlang.org/
265+
[Grafana]: https://img.shields.io/badge/Grafana-35495E?style=for-the-badge&logo=grafana&logoColor=4FC08D
266+
[Grafana-url]: https://grafana.com/
267+
[Tailwind]: https://img.shields.io/badge/TailwindCSS-DD0031?style=for-the-badge&logo=tailwindcss&logoColor=white
268+
[Tailwind-url]: https://tailwindcss.com/
269+
[Node.js]: https://img.shields.io/badge/Node-4A4A55?style=for-the-badge&logo=nodedotjs&logoColor=FF3E00
270+
[Node-url]: https://nodejs.org/en/
271+
[Express]: https://img.shields.io/badge/Express-FF2D20?style=for-the-badge&logo=express&logoColor=FF3E00
272+
[Express-url]: https://expressjs.com/
273+
[Redux]: https://img.shields.io/badge/RTK-563D7C?style=for-the-badge&logo=redux&logoColor=white
274+
[Redux-url]: https://redux.js.org/
275+
[Webpack]: https://img.shields.io/badge/Webpack-0769AD?style=for-the-badge&logo=webpack&logoColor=white
276+
[Webpack-url]: https://webpack.js.org/guides/getting-started/
277+
[Docker]: https://img.shields.io/badge/Docker-0769AD?style=for-the-badge&logo=docker&logoColor=white
278+
[Docker-url]: https://www.docker.com/

‎assets/demo.gif‎

6.41 MB
Loading

‎assets/finalabout.jpg‎

484 KB
Loading

0 commit comments

Comments
 (0)