Images Cloud

Table of Contents

• Images Cloud
  • Table of Contents
  • Introduction
  • Prerequisites
  • Installation
  • Sample user
  • Endpoints
    • Client endpoints
    • Server endpoints
      • Server endpoints protected by authentication
  • Production build
  • Tests
  • Troubleshooting
  • Contributing
  • Contact
  • License
  • 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 v20.10.17
• Docker 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 v20.10.0
• Yarn 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:

   git clone https://github.com/JakubKorytko/images-cloud

2. Enter the project directory:

   cd images-cloud

3. Create .env file in root directory images-cloud/ (or set environment variables manually):

   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 file for an example.

4. Start the application:

   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:

client:
  build:
    # ...
    target: production
# ...
server:
  build:
    # ...
    target: production

And then run the following command:

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:

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:

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
• 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 jakub@korytko.me.

License

This project is released under the MIT License. See the 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