Install Cyca With Docker

This document will guide you through installing Cyca with Docker.

Summary

git clone https://github.com/RichardDern/cyca_docker_compose cyca
cd cyca
cp .env.example .env

Change settings as needed, mainly APP_URL, database and email.

docker-compose up -d

Detailed workthrough

Install Docker and docker-compose

If you don’t already have installed docker and docker-compose, now is the time to do it !

Optional: install git

git is not required to install Cyca. However, and despite the repository should not change often, it will ensure you use the most up-to-date files to install Cyca.

Download Cyca helper files

A bunch of files are provided to help you quickly run Cyca. You can directly download the archive, or use git to clone the repository.

git clone https://github.com/RichardDern/cyca_docker_compose
cd cyca_docker_compose

You can clone the repository in a more “convenient” directory if you want:

git clone https://github.com/RichardDern/cyca_docker_compose cyca
cd cyca

Create a configuration file

Copy the .env.example file to .env:

cp .env.example .env

Modify this file according to your needs. Every option is documented, some require change, some could be changed, and some shouldn’t need to be changed.

Set Cyca’s URL, and adjust email settings. APP_KEY will be set automatically.

If you change database settings, remember to modify provided docker-compose.yaml to reflect these changes. This is especially important if you change database’s password.

Run Cyca and test everything is running properly

You can now run Cyca using the following command:

docker-compose up

If everything runs properly, you should see a bunch of log lines. These two are likely to be the more important:

[...]
app_1         | [09-Oct-2020 20:16:33] NOTICE: fpm is running, pid 1
[...]
app_1         | [09-Oct-2020 20:16:33] NOTICE: ready to handle connections

If you see this, and assuming you are using the default values provided, you should be able to reach Cyca to the following URL:

http://<ip_or_hostname>

Replace <ip_or_hostname> with the IP address or the hostname of the server running Cyca.

You should see Cyca’s login page. If you don’t, you might have to check docker’s output, or even Cyca’s log, to determine what is going on.

To consult Cyca’s log files, you can run the following command, while keeping the containers running:

docker exec cyca_app_1 ls /app/storage/logs

There should be at least one file, named laravel-(current date).log. To read it, run:

docker exec cyca_app_1 cat /app/storage/logs/laravel-(current date).log

These commands assume cyca_app_1 is your container’s name.

Allow external access to Cyca

You will notice Cyca runs a proxy service, which is a nginx server, using provided configuration file (nginx.conf). This service will expose the port 80, so your instance is directly accessible from the right HTTP port, but you might need to change it to a different port if it’s already used by another application on your server.

This service also takes care of a very important aspect of Cyca: websockets, which provides real-time notifications. For this specific reason, it is highly recommended to use provided settings and run a reverse-proxy on top of Cyca’s installation to ensure websockets work properly, and to setup HTTPS connectivity.

However, you are free not to use Cyca’s embedded reverse proxy at all. You can do this by commenting all the lines related to the proxy service in the docker-compose.yaml file.

Should you do this, you will need to take care of proper php-fpm and websockets handling in your own, full-blown reverse-proxy configuration.

Finally, you could also keep using Cyca’s proxy and add the certificate handling yourself to the nginx.conf file.

Run Cyca for good

We just ran the docker image in the foreground, which is convenient to test the setup but not for a real-life use of Cyca, so stop everything by pressing Ctrl+C. Now, run Cyca for good:

docker-compose up -d

You can now navigate to Cyca’s URL and register your first user !