Memor-i Studio

Memor-i is a Memory card game especially tailored to meet the needs of blind people.

Memor-i Studio, is an online games repository that people can use in order to create their own flavors of Memor-i game!

Installation Instructions

Please read thoroughly the following guid/steps, to set up Memor-i Studio.

Pre-installation requirements

This project assumes working installations of the following technologies / components:

1. PHP (version >= 8.1)

2. MySQL

3. composer (PHP package manager)

4. npm (Front-end dependencies package manager)

5. Laravel

6. Apache Web Server (or any other Web Server you are comfortable with)

First time install (setup database and install dependencies)

Docker option

You can use the docker-compose.yml file that exists at project roo, to quickly set up a docker container.

Just run

docker compose up

To fire up the container.

Then, you can enter the container by running

docker exec -it memori_studio_server bash

And from there, you can run all the php artisan, composer, and npm commands.

Language and Framework Dependencies

Make sure php 8.1 is installed.

Install the Laravel IMAP dependencies:

sudo apt-get install php*-imap php*-mbstring php*-mcrypt && sudo apache2ctl graceful

After cloning the project, create an .env file (should be a copy of .env.example), containing the information about your database name and credentials.

Environment file, Laravel/backend dependencies

After cloning the project, create an .env file (should be a copy of .env.example), containing the information about your database name and credentials. After that, download all Laravel dependencies through Composer, by running

composer install

composer update

Front-end dependencies

After all Laravel dependencies have been downloaded, it's time to download all Javascript libraries and dependencies. We achieve that by using nodejs and its package manager, npm.

A convenient way of installing multiple versions of nodejs and npm on a machine, is by installing and using Node Version Manager, nvm.

So, when in project root directory, and after npm has been installed correctly, run

It is very easy to install multiple versions of NodeJS and npm, by using Node Version Manager (nvm).

If you are using nvm, run this command in order to sync to the correct NodeJS version for the project:

nvm install

nvm use 

npm install

To download and install all libraries and dependencies.

Compiling front-end assets

This project uses Webpack and Laravel Mix which is a popular toolkit for automating painful or time-consuming tasks, like SASS compiling and js/css concatenation and minification.

Since it is built upon webpack, you can use the following commands to compile the front-end assets:

npm run dev #for dev builds

npm run prod #for production builds

npm run watch #for dev builds, also enables hot changes on the files 

Database

Create the database schema:

php artisan config:clear

php artisan migrate

Add seed data to DB

Run php artisan db:seed in order to insert the starter data to the DB by using Laravel seeder

Permissions

Fix permissions for storage directory:

sudo chown -R ${USER}:www-data storage

sudo chmod -R 755 storage bootstrap/cache

cd storage/

sudo find . -type f -exec chmod 664 {} \;

sudo find . -type d -exec chmod 775 {} \;

The commands above are also available with the permissions script, in the root directory of the project.

You can use it like this:

sudo ./set-file-permissions.sh www-data project_memori .

Note: project_memori should be the name of the server user.

Apache configuration (optional)

cat /etc/apache2/sites-available/memoristudio.conf

<VirtualHost *:80>
    ServerName dev.memoristudio
    DocumentRoot "/path/to/memoristudio/public"
    <Directory "/path/to/memoristudio/public">
        AllowOverride all
    </Directory>
</VirtualHost>

Make the symbolic link:

cd /etc/apache2/sites-enabled && sudo ln -s ../sites-available/memoristudio.conf

Enable mod_rewrite and restart apache:

sudo a2enmod rewrite && sudo service apache2 restart

Without apache custom configuration

Navigate to the root directory of the project and run:

php artisan serve

and navigate to localhost:8000.

And have write access to /home directory.

---

Required steps for the server

1. Allow the uploading large files

In order for the app to work as expected, max size of files and timeout time must be set on the appropriate configuration files for php-fpm and nginx.

1. For nginx

   edit the /etc/nginx/sites-enabled/memoristudio.server.org file and add fastcgi_read_timeout 300;

2. For php-fpm

   edit /etc/php/8.1/fpm/ (or the corresponding php version) and change:

 max_input_time = 300
 
 post_max_size = 200M
 
 upload_max_filesize = 200M

2. Converting audio files to mpr with CBR (constant bit rate)

This project allows users to upload audio files. In order for the desktop application of Memor-i to operate correctly, these files need to me in .mp3 format and have a CBR (constant bit rate), not a VBR (variable bit rate) . See more This project converts uploaded audio files appropriately, on the fly. For this to happen, we use avconv library. To install this library in a Unix-based machine, check this post.

You can see and modify the command we use for coverting the files in public/convert_to_mp3.sh.

3. Converting image files to .ico files

This project includes special functionality to convert a game flavor cover image file into a .ico file, for usage when the game runs. In order to accomplish this, we use ImageMagick tool. ImageMagick can be installed like this: apt-get install imagemagick

4. Building Windows executables

When an admin user publishes a game flavor, A .jar file is built for this game flavor. In addition, this application uses Launch4J in order to build also the windows executable and Inno setup to build the installer.

The launch4J application is included in public/build_app/launch4j as a standalone application. In order to run Launch4J, you will also need to install Java.

Also, you will need to install the zip and unzip commands in Linux:

• sudo apt install zip
• sudo apt install unzip

For building the Windows installer for the .exe that Launch4J built, this project uses Inno Setup-exe-builder, an external service for compiling executables to Windows installers.

So you will need to setup and have this service running, and then change the WINDOWS_SETUP_SERVICE_URL variable in .env.

---

Deploying

You can run either php artisan serve or set up a symbolic link to /path/to/project/public directory and navigate to http://localhost/{yourLinkName}

Required steps for Production server

Required steps for uploading large files

In order for the app to work as expected, max size of files and timeout time must be set on the appropriate configuration files for php-fpm and nginx.

1. For nginx

   edit the /etc/nginx/sites-enabled/memoristudio.scify.org file and add fastcgi_read_timeout 300;

2. For php-fpm

   edit /etc/php/VERSION/fpm/ (or the corresponding php version) and change:

   • maxinputtime = 300
   • postmaxsize = 200M
   • upload_max_filesize = 200M

3. Make sure that the project_memori user belongs to group www-data

Mailgun Considerations

Make sure that the production server IP is whitelisted in Mailgun.

License

This project is open-sourced software licensed under the Apache License, Version 2.0.

Memor-i Studio has been created by Science For You (SciFY), a Greek not-for-profit organization.

The Memor-i Studio project has been funded by Public Benefit Foundation John S. Latsis