https://github.com/jakubkorytko/images-cloud
A universal project that allows you to host a comprehensive cloud-based image gallery application with various tools for image manipulation
https://github.com/jakubkorytko/images-cloud
file-hosting image-gallery jwt mit-license open-source
Last synced: 16 days ago
JSON representation
A universal project that allows you to host a comprehensive cloud-based image gallery application with various tools for image manipulation
- Host: GitHub
- URL: https://github.com/jakubkorytko/images-cloud
- Owner: JakubKorytko
- License: mit
- Created: 2022-08-02T13:49:56.000Z (almost 4 years ago)
- Default Branch: main
- Last Pushed: 2023-12-29T13:12:47.000Z (over 2 years ago)
- Last Synced: 2025-03-01T02:33:53.332Z (over 1 year ago)
- Topics: file-hosting, image-gallery, jwt, mit-license, open-source
- Language: TypeScript
- Homepage:
- Size: 9.5 MB
- Stars: 1
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# Images Cloud
[](https://img.shields.io/github/v/tag/JakubKorytko/images-cloud?style=for-the-badge&label=version)
[](https://img.shields.io/github/license/JakubKorytko/images-cloud?style=for-the-badge&label=license)
## Table of Contents
- [Images Cloud](#images-cloud)
- [Table of Contents](#table-of-contents)
- [Introduction](#introduction)
- [Prerequisites](#prerequisites)
- [Installation](#installation)
- [Sample user](#sample-user)
- [Endpoints](#endpoints)
- [Client endpoints](#client-endpoints)
- [Server endpoints](#server-endpoints)
- [Server endpoints protected by authentication](#server-endpoints-protected-by-authentication)
- [Production build](#production-build)
- [Tests](#tests)
- [Troubleshooting](#troubleshooting)
- [Contributing](#contributing)
- [Contact](#contact)
- [License](#license)
- [TODO / Upcoming features](#todo--upcoming-features)
## Introduction
Images Cloud is a cloud-based image gallery application that offers users a comprehensive hosting experience that goes beyond traditional solutions. This versatile platform caters to the needs of both individuals and organizations, presenting itself as a sophisticated answer to the quest for sophisticated image hosting.
In addition, Images Cloud goes beyond mere hosting capabilities by providing robust image manipulation tools. This additional feature enhances the application's utility and allows users to unleash their creative potential in the digital realm.
The application's user-friendly interface has been thoughtfully designed to ensure a seamless experience. This care extends to responsiveness and adaptability, ensuring optimal viewing across devices and screen sizes. In essence, Images Cloud seamlessly blends functionality with user-centric design, setting it apart in the field of cloud-based image hosting solutions.
## Prerequisites
**Note:** Versions stated below are the ones used during development.\
Other versions may work as well, but they have not been tested.
- [Docker](https://www.docker.com/) `v20.10.17`
- [Docker Compose](https://docs.docker.com/compose/) `v2.6.1`
**This app is designed to work with Docker.**\
If you want to run it without Docker, you will need to install:
- [Node.js](https://nodejs.org/en/) `v20.10.0`
- [Yarn](https://yarnpkg.com/) `v1.22.21`
And check the both Dockerfiles and the `docker-compose.yml` file for the required steps.\
(You also need to handle the environment variables yourself in this case.)
## Installation
1. Clone the repository:
```bash
git clone https://github.com/JakubKorytko/images-cloud
```
1. Enter the project directory:
```bash
cd images-cloud
```
1. Create `.env` file in root directory `images-cloud/` (or set environment variables manually):
```bash
CLIENT_PORT= # port of the client app
SERVER_PORT= # port of the server app
SERVER_URL= # url of the server app (with port), used in the client app
CONNECTION_TEST_INTERVAL= # interval between connection tests (in ms)
JWT_EXPIRATION= # token expiration time (in minutes)
APP_SECRET= # json web token, you can generate one here: https://jwt.io
```
*Refer to the [`.env.example`](.env.example) file for an example.*
1. Start the application:
```bash
docker compose up -d
```
*Make sure that docker is running on your machine before executing this command.*
## Sample user
The app comes with a sample user that you can use to log in and test the app.
- username: `stanley`
- password: `qwerty123`
## Endpoints
### Client endpoints
- `GET /` - main page
- `GET /login` - login page
- `GET /status` - server status page
The `/` endpoint is protected by authentication. To access it, you need to log in first.
If you try to access it without logging in, you will be redirected to the login page.
### Server endpoints
The client app uses the server app for authentication and data storage.
There is no need to use the server app directly
(except for the `/` endpoint which is used to manage the database),
but if you want to (or want to use the API for something else),
here are the available endpoints:
- `GET /` - database management page
- `GET /health` - health check endpoint
- `POST /addUser` - add user endpoint, payload:
- `username` - string, length between 6 and 20 characters
- `password` - string, length between 6 and 50 characters
- `POST /deleteUser` - delete user endpoint, payload:
- `username` - string
- `POST /login` - login endpoint, payload:
- `username` - string
- `password` - string
#### Server endpoints protected by authentication
These endpoints require a valid JWT token to work. The token should be passed in the `Authorization` header with the `Bearer` prefix.
- `POST /auth` - authentication endpoint, returns a username if the token is valid
- `GET /download/:photo` - download photo from the database, params:
- `photo` - string, photo name
- `GET /delete/:photo` - delete photo from the database, params:
- `photo` - string, photo name
- `GET /photo/:photo` - get photo from the database, params:
- `photo` - string, photo name
- `GET /thumbnail/:thumb` - get thumbnail from the database, params:
- `thumb` - string, thumbnail name
- `GET /progressive/:thumb` - get progressive image from the database, params:
- `thumb` - string, progressive image name
- `GET /photos` - get all photos from the database
- `POST /upload` - upload photo to the database, payload (form-data):
- `image` - file, photo to upload
- `name` - string, photo name
## Production build
To run the production version of the app, change the `target` properties in the `docker-compose.yml` file to `production`:
```yml
client:
build:
# ...
target: production
# ...
server:
build:
# ...
target: production
```
And then run the following command:
```bash
docker compose up -d
```
If you want to build the production version of the app without docker (for example, to deploy it to a hosting service),
check the `Dockerfile` files in both `client` and `server` directories
and the `docker-compose.yml` file for the required steps.
(You also need to handle the environment variables and install the dependencies yourself in this case.)
## Tests
---
**As for the `v0.1.1` version, the tests do not cover the majority of the code, and most of the existing tests do not pass due to changes in the project structure. This will be fixed in the next patch.**
---
To run the tests, use the following command:
```bash
docker compose run --rm app yarn test
```
Where `app` is the one of the following services:
- `client`
- `server`
## Troubleshooting
If you are using Windows or your git client converts line endings to CRLF,
you may encounter the following error when trying to run the app:
```bash
error Expected linebreaks to be 'LF' but found 'CRLF' linebreak-style
```
This is caused by the fact that the project uses the eslint.
To fix this, you can either:
- change the line endings to LF (recommended)
- by simply running `yarn eslint --fix` in the both `client` and `server` directories
- disable (or change) the eslint rule
- read more about it [here](https://eslint.style/rules/js/linebreak-style)
- add the instructions (e.g. using dos2unix) to the `Dockerfile` files to convert the line endings automatically
Note that if you change the line endings to LF and decide not to disable the eslint rule,
your editor or git client may convert them back to CRLF.
Make sure your editor and git config are set up correctly.
## Contributing
If you find issues or have suggestions for improvements,
feel free to open an issue or submit a pull request.
Contributions are welcome!
## Contact
If you have any questions, feel free to contact me at .
## License
This project is released under the MIT License. See the [LICENSE](LICENSE) file for details.
## TODO / Upcoming features
This is a list of features that lead to the `v0.2.0` release:
(This list is not exhaustive and may change at any time.
Patch versions may and probably will be released in the meantime.
Keep in mind that the order of the items is not necessarily the order in which they will be implemented.)
- [ ] Add more tests and fix the existing ones
- [ ] Improve the existing API structure
- [ ] Improve the UI
- [ ] Clean up the code
- [ ] Add new technologies (for both the client and the server) and refactor the code accordingly
- [ ] Implement CI/CD
- [ ] Look for and fix potential security issues, vulnerabilities, and bugs
- [ ] Protect routes on the server side