adds documentation (#250)

* adds documentation

* updates in user docs

* documentation

Co-authored-by: styiannis <1515939+styiannis@users.noreply.github.com>

README.md

@@ -100,6 +100,12 @@ There are two ways to run MediaCMS, through Docker Compose and through installin
 Several options are available on cms/settings.py, most of the things that are allowed or should be disallowed are described there. It is advisable to override any of them by adding it to cms/local_settings.py. All configuration options will be documented gradually on the [Configuration](docs/Configuration.md) page.
 
 
+## Documentation
+* [Users documentation](docs/user_docs.md) page
+* [Administrators documentation](docs/admins_docs.md) page
+* [Developers documentation](docs/developers_docs.md) page
+
+
 ## Technology
 This software uses the following list of awesome technologies: Python, Django, Django Rest Framework, Celery, PostgreSQL, Redis, Nginx, uWSGI, React, Fine Uploader, video.js, FFMPEG, Bento4
 

docs/Docker_Compose.md

@@ -30,6 +30,13 @@ docker-compose up
 
 This will download all MediaCMS related Docker images and start all containers. Once it finishes, MediaCMS will be installed and available on http://localhost or http://ip
 
+A user admin has been created with random password, you should be able to see it at the end of migrations container, eg
+
+```
+migrations_1     | Created admin user with password: gwg1clfkwf
+```
+
+or if you have set the ADMIN_PASSWORD variable on Dockerfile, that variable will be set as the admin user's password
 
 ## Update
 

docs/admins_docs.md

@@ -0,0 +1,30 @@
+# Administrators documentation
+
+## Table of contents
+- [Uploading media](#uploading-media)
+- [Manage pages](#manage-pages)
+- [Django admin dashboard](#django-admin-dashboard)
+- [On portal workflow](#on-portal-workflow)
+- [On user roles](#on-user-roles)
+- [Adding languages for Captions and subtitles](#adding-languages-for-captions-and-subtitles)
+- [Add/delete categories and tags](#add-delete-categories-and-tags)
+- [Video transcoding](#video-transcoding)
+
+
+## Manage pages
+
+## Django admin dashboard
+
+## On portal workflow
+Who can publish content, how content appears on public listings.Difference between statuses (private, unlisted, public)
+
+## On user roles
+Differences over MediaCMS manager, MediaCMS editor, logged in user
+
+## Adding languages for Captions and subtitles
+
+## Add/delete categories and tags
+Through the admin section - http://your_installation/admin/
+
+## Video transcoding
+Add / remove resolutions and profiles through http://your_installation/admin/encodeprofile

docs/developers_docs.md

@@ -0,0 +1,77 @@
+# Developers documentation
+
+## Table of contents
+- [System architecture](#system-architecture)
+- [API documentation](#api-documentation)
+- [Working with Docker tips](#working-with-docker-tips)
+- [How video is transcoded](#how-video-is-transcoded)
+
+
+## System architecture
+
+## API documentation
+API is documented using Swagger - checkout ot http://your_installation/swagger
+This page allows you to login to perform authenticated actions - it will also use your session if logged in. 
+
+
+## Working with Docker tips
+
+To perform the Docker installation, follow instructions to install Docker + Docker compose (docs/Docker_Compose.md) and then build/start docker-compose-dev.yaml . This will run the frontend application on port 8088 on top of all other containers (including the Django web application on port 80)
+
+```
+docker-compose -f docker-compose-dev.yaml build
+docker-compose -f docker-compose-dev.yaml up
+```
+
+### Frontend application changes
+Eg change `frontend/src/static/js/pages/HomePage.tsx` , dev application refreshes in a number of seconds (hot reloading) and I see the changes, once I'm happy I can run
+
+```
+docker-compose -f docker-compose-dev.yaml -T frontend npm run dist
+```
+
+And then in order for the changes to be visible on the application while served through nginx, 
+
+```
+cp -r frontend/dist/static/* static/
+```
+
+POST calls: cannot be performed through the dev server, you have to make through the normal application (port 80) and then see changes on the dev application on port 8088. 
+Make sure the urls are set on `frontend/.env` if different than localhost
+
+
+Media page: need to upload content through the main application (nginx/port 80), and then use an id for page media.html, for example `http://localhost:8088/media.html?m=nc9rotyWP`
+
+There are some issues with CORS too to resolve, in order for some pages to function, eg the manage comments page
+
+```http://localhost:8088/manage-media.html px manage_media
+```
+
+### Backend application changes
+After I make changes to the django application (eg make a change on `files/forms.py`) in order to see the changes I have to restart the web container
+
+```
+docker-compose -f docker-compose-dev.yaml restart web
+```
+
+## How video is transcoded
+
+Original files get uploaded to the application server, and they get stored there as FileFields.
+
+If files are videos and the duration is greater than a number (defined on settings, I think 4minutes), they are also broken in chunks, so one Encode object per chunk, for all enabled EncodeProfiles.
+
+Then the workers start picking Encode objects and they transcode the chunks, so if a chunk gets transcoded correctly, the original file (the small chunk) gets replaced by the transcoded file, and the Encode object status is marked as 'success'.
+
+
+original.mp4 (1G, 720px)--> Encode1 (100MB, 240px, chunk=True), Encode2 (100MB, 240px, chunk=True)...EncodeXX (100MB, 720px, chunk=True) ---> when all Encode objects are success, for a resolution, they get concatenated to the original_resolution.mp4 file and this gets stored as Encode object (chunk=False). This is what is available for download.
+
+Apparently the Encode object is used to store Encoded files that are served eventually (chunk=False, status='success'), but also files while they are on their way to get transcoded (chunk=True, status='pending/etc')
+
+(Parenthesis opening)
+there is also an experimental small service (not commited to the repo currently) that speaks only through API and a) gets tasks to run, b) returns results. So it makes a request and receives an ffmpeg command, plus a file, it runs the ffmpeg command, and returns the result.I've used this mechanism on a number of installations to migrate existing videos through more servers/cpu and has worked with only one problem, some temporary files needed to be removed from the servers (through a periodic task, not so big problem)
+(Parenthesis closing)
+
+
+When the Encode object is marked as success and chunk=False, and thus is available for download/stream, there is a task that gets started and saves an HLS version of the file (1 mp4-->x number of small .ts chunks). This would be FILES_C
+
+This mechanism allows for workers that have access on the same filesystem (either localhost, or through a shared network filesystem, eg NFS/EFS) to work on the same time and produce results. 

docs/user_docs.md

@@ -0,0 +1,208 @@
+# Users documentation
+
+## Table of contents
+- [Uploading media](#uploading-media)
+- [Downloading media](#downloading-media)
+- [Adding captions/subtitles](#adding-captionssubtitles)
+- [Search media](#search-media)
+- [Share media](#share-media)
+- [Embed media](#embed-media)
+- [Customize my profile options](#customize-my-profile-options)
+
+## Uploading media
+
+### How to Upload Media
+
+Uploading media is as simple as clicking the _Upload Media_ button, waiting for media to upload, and then clicking the media to add metadata (title, description etc.) by filling out a form.
+
+#### Click Upload Button
+
+Click the _Upload Media_ button from the right-side of the screen at the top:
+
+<p align="left">
+    <img src="./images/Click-Upload-Media-button.png"/>
+</p>
+
+#### Upload Page
+
+Clicking the _Upload Media_ button takes you to the upload page at a URL like this:
+
+https://demo.mediacms.io/upload
+
+#### Click Browse Button
+
+Here you should click the _"Browse your files"_ button (or drag and drop a file from your desktop):
+
+<p align="left">
+    <img src="./images/Click-Browse-button.png"/>
+</p>
+
+#### Select media file and click Open button
+
+Select the media file that you want to upload and click the _"Open"_ button:
+
+<p align="left">
+    <img src="./images/Select-Media-File-Click-Open.png"/>
+</p>
+
+#### Wait for file to upload
+
+Wait for the file to finish uploading:
+
+<p align="left">
+    <img src="./images/Uploading.png"/>
+</p>
+
+#### Pause uploading
+
+If you want you can pause upload by clicking _Pause button_:
+
+<p align="left">
+    <img src="./images/Pause-button.png"/>
+</p>
+
+#### Continue uploading
+
+Continue upload by clicking _Continue button_:
+
+<p align="left">
+    <img src="./images/Continue-button.png"/>
+</p>
+
+#### Wait for media to finish Processing
+
+Wait for the media file to finish Processing:
+
+<p align="left">
+    <img src="./images/Processing.png"/>
+</p>
+
+#### Click View media button
+
+Click the View media button to open the media page:
+
+<p align="left">
+    <img src="./images/Click-View-media-button.png"/>
+</p>
+
+#### Media will be in the encoding queue
+
+The media will take some time to finish encoding (MediaCMS will transcode the file to several formats and resolutions). Meanwhile you can edit the media file to add metadata.
+
+#### Click Edit Media button
+
+Click the EDIT MEDIA button to add metadata and configure the poster image:
+
+<p align="left">
+    <img src="./images/Click-Edit-Media-button.png"/>
+</p>
+
+#### Add Metadata (Summary, Description etc.)
+
+Make sure you fill in all the required fields, and try to complete as many of the non-required fields as possible. This ensures the database is populated with useful meta-data to help others access useful information about you and your video.
+
+<p align="left">
+    <img src="./images/Edit-Media-Metadata-1.png"/>
+</p>
+
+<p align="left">
+    <img src="./images/Edit-Media-Metadata-2.png"/>
+</p>
+
+
+
+## Downloading media
+
+MediaCMS offers a configurable option whereby users can make their media files available for download. Downloads are available for transcoded files, and the original file.
+
+#### How To Enable Download
+
+Visit the media view page and choose the EDIT MEDIA button.
+
+Select the checkbox for "Allow Downloads"
+
+#### How To Download Media
+
+Visit the media view page and click the DOWNLOAD button below the video player.
+
+<p align="left">
+    <img src="./images/Click-Download-Button.png">
+</p>
+
+Choose the version you wish to download - a transcoded file or the original file:
+
+<p align="left">
+    <img src="./images/Click-version-download.png">
+</p>
+
+Choose Save File and click the OK button.
+
+<p align="left">
+    <img src="./images/Save-File.png">
+</p>
+
+
+
+## Adding captions/subtitles
+
+With MediaCMS you can add subtitles/captions to your video by uploading a subtitles file in the popular .vtt format.
+
+### Visit Media Page & Click EDIT SUBTITLE Button
+
+Visit the "single media page" for the media you wish to add subtitles/captions to and click the EDIT SUBTITLES button:
+
+<p align="left">
+    <img src="./images/Click-EDIT-SUBTITLE.png"/>
+</p>
+
+### Upload Subtitles in .vtt Format
+
+Click the Language menu to select the correct language for your Subtitles/Captions file:
+
+<p align="left">
+    <img src="./images/Click-Subtitle-Language-Menu.png"/>
+</p>
+
+Choose the correct Language for your file:
+
+<p align="left">
+    <img src="./images/Subtitles-captions1.png"/>
+</p>
+
+Click Browse to find a subtitles/captions file on your computer (if your file is not in the .vtt format, you may find a conversion service on the Internet):
+
+<p align="left">
+    <img src="./images/Subtitles-captions2.png"/>
+</p>
+
+Choose a .vtt subtitles/captions file from your computer:
+
+<p align="left">
+    <img src="./images/Subtitles-captions3.png"/>
+</p>
+
+Click the Add button to add the file to your media:
+
+<p align="left">
+    <img src="./images/Click-ADD-button.png"/>
+</p>
+
+### View Subtitles/Captions in Video Player
+
+You can now watch the captions/subtitles play back in the video player - and toggle display on/off by clicking the CC button:
+
+<p align="left">
+    <img src="./images/CC-display.png"/>
+</p>
+
+## Search media
+How search can be used
+
+## Share media
+How to share media
+
+## Embed media
+How to use the embed media option
+
+## Customize my profile options
+Customize profile and channel