velkolevski/cloud-gallery-made-by-velin repository overview

⁠Cloud Gallery — OCI Installation Guide

Cloud Gallery is distributed as a Docker Compose OCI artifact. This means that you do not need to download the source code or a docker-compose.yml file. Docker retrieves the application definition, the Spring Boot image, and the PostgreSQL image from the registry.

Your Cloud Gallery accounts, saved application data, and AWS configuration are stored by PostgreSQL in a local Docker volume on your machine. Your uploaded images remain in your personal S3 bucket. None of this user data is included in the downloaded application image or shared with other installations.

⁠Requirements

• Docker Desktop with Docker Compose
• Docker Desktop must be running
• Access to the Cloud Gallery Docker Hub repository while it is private

Check that Docker Compose is available:

docker compose version

⁠1. Sign in to Docker Hub

This step is required while the repository is private:

docker login

Sign in with a Docker Hub account that has permission to access the repository. If the repository becomes public, this step will no longer be required.

⁠2. Create a local installation folder

Create an empty folder for your Cloud Gallery configuration and open a terminal inside it:

mkdir cloud-gallery
cd cloud-gallery

The folder will contain only your private .env configuration file. The application itself remains in Docker.

⁠3. Create the environment file

Create a file named .env inside the cloud-gallery folder with the following content:

APP_PORT=8080
POSTGRES_DB=cloud_gallery
POSTGRES_USER=cloud_gallery
POSTGRES_PASSWORD=replace_with_a_strong_unique_password

Replace replace_with_a_strong_unique_password with your own strong password. On macOS or Linux, you can generate one with:

openssl rand -hex 32

Paste the generated value after POSTGRES_PASSWORD=. Do not add spaces around the = sign.

The password protects this installation's PostgreSQL database. It is not your Cloud Gallery login password. Do not share or commit the .env file.

You may change APP_PORT if port 8080 is already in use. For example:

APP_PORT=8082

⁠4. Start Cloud Gallery

Run the following command from the folder that contains .env:

docker compose --env-file .env -p cloud-gallery -f oci://docker.io/velkolevski/cloud-gallery-made-by-velin:compose-1.0.0 up -d

Docker Compose may show the variables used by the OCI artifact and ask for confirmation. Check that APP_PORT, POSTGRES_DB, POSTGRES_USER, and POSTGRES_PASSWORD are set, then enter y to continue only if you trust the artifact source.

Docker downloads and starts two containers:

• Cloud Gallery — the Spring Boot application
• PostgreSQL — the private database for this installation

PostgreSQL starts first. Cloud Gallery starts after the database becomes healthy.

⁠5. Open the application

If .env contains APP_PORT=8080, open:

http://localhost:8080

If you selected another port, use that port instead. For example, APP_PORT=8082 means that the application is available at:

http://localhost:8082

Create your Cloud Gallery account. Then open the Help Guide in the application to configure your personal AWS S3 bucket and IAM credentials.

⁠Check the container status

docker compose --env-file .env -p cloud-gallery -f oci://docker.io/velkolevski/cloud-gallery-made-by-velin:compose-1.0.0 ps

The PostgreSQL container should show healthy, and the application container should show Up.

⁠View application logs

docker compose --env-file .env -p cloud-gallery -f oci://docker.io/velkolevski/cloud-gallery-made-by-velin:compose-1.0.0 logs -f app

Press Ctrl+C to stop following the logs. This does not stop the application.

⁠Stop Cloud Gallery

docker compose --env-file .env -p cloud-gallery -f oci://docker.io/velkolevski/cloud-gallery-made-by-velin:compose-1.0.0 down

Your database remains stored in the local Docker volume. Run the start command again whenever you want to use the application.

⁠Update to a newer release

When a newer OCI release is published, replace compose-1.0.0 in the commands with the new version supplied by the project owner, then run the start command again. Docker downloads the required updated images while preserving the local database volume.

⁠Permanently delete this installation

The following command removes the containers, network, and database volume:

docker compose --env-file .env -p cloud-gallery -f oci://docker.io/velkolevski/cloud-gallery-made-by-velin:compose-1.0.0 down -v

Warning: The -v option permanently deletes the PostgreSQL database, including all Cloud Gallery accounts and saved gallery data for this installation. Use it only when you intentionally want to erase everything.

⁠Troubleshooting

⁠Docker cannot access the repository

Run docker login and confirm that your Docker Hub account has access to the private repository.

⁠A variable is shown as <unset>

Confirm that:

• the file is named exactly .env;
• the command is executed from the folder containing .env;
• the command includes --env-file .env;
• every line in .env uses the NAME=value format.

Do not continue when one of the PostgreSQL variables is shown as <unset>.

⁠Port 8080 is already in use

Change APP_PORT in .env to another available port, such as 8082, and run the start command again.

⁠The application does not open

Check the container status and application logs using the commands above. The first startup may take a short time while Docker downloads the images and PostgreSQL initializes the new database.