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 for the first time

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

After the first installation, stop the existing application and database containers without removing them:

docker stop cloud-gallery-app-1 cloud-gallery-postgres-db-1

This keeps both containers and the cloud-gallery_pgdata PostgreSQL volume. Registered users, saved AWS settings, and other database records remain available for the next start.

⁠Start Cloud Gallery again

Start the existing PostgreSQL container first:

docker start cloud-gallery-postgres-db-1

Wait a few seconds for PostgreSQL to become healthy, then start the application:

docker start cloud-gallery-app-1

You can verify the status with:

docker ps

Open Cloud Gallery using the same port selected during the first installation. You do not need to recreate .env or run the OCI Compose installation command again while these containers still exist.

⁠Update to a newer release

An ordinary docker start starts the existing containers and does not install a newer application image. When a newer OCI release is published, replace compose-1.0.0 below with the version supplied by the project owner and run:

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 downloads the required updated images and recreates containers when necessary. Because the same cloud-gallery project and PostgreSQL volume are used, the database remains stored locally.

⁠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

During the first installation, change APP_PORT in .env to another available port, such as 8082, before running the Compose command.

If the containers already exist, changing .env alone does not modify their current port mapping. The containers must be recreated through Docker Compose for a new port mapping to take effect.

⁠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.

⁠A container name cannot be found

List all existing containers and find the Cloud Gallery and PostgreSQL container names:

docker ps -a

The documented names are created when the installation uses the project name cloud-gallery shown in the first-start command.