image::images/500x1500-banner-with-desc.png[]
= SolarDoc 🌌✨
SolarDoc is a dynamic online editor which allows you to create beautiful presentations using AsciiDoc in your browser. Collaborate with your colleagues and friends in the online editor and freely share your work with anyone!
🚀 The latest preview of Solardoc can be viewed https://solardoc.htl-leonding.ac.at[here]! 🚀
== Problem & Background 🛑
=== Given Situation ⚡
There is no collaborative environment for creating presentations using AsciiDoc. As such, it is difficult to efficiently develop presentations. Currently, there are tools & plugins available to render real-time AsciiDoc and AsciiDoc presentations using revael.js, but they either lack functionality or require monthly license payments. As such they are unsuitable for students and teachers given the college environment.
=== Potential for improvement 💡
== Goals 📈
To allow students and teachers to more efficiently create, edit and share presentations. They should be able to easily work together and have a co-working space, where they can manage an entire presentation without the need for external tools. The editor should be performant and responsive, without having to worry too much about rendering time.
== Potential & Risks ⚠️
== Development 🛠
=== Setup
To set up the project please install PNPM and Node>=16. Then run the following commands:
In this project we use a PNPM monorepo structure to manage the various dependencies and packages. As such, PNPM can NOT be replaced with NPM or Yarn. This is very important to not break the project.
=== Development
To start the various development servers go to the individual packages and run their respective commands in their
directories or use pnpm run --filter @solardoc/<package> <command>.
pnpm run dev or pnpm run --filter @solardoc/frontend devpnpm run start or pnpm run --filter @solardoc/rest-api startThe Redis DB is Docker-only and as such has to be started using the following command:
=== Define the ENV vars
The project uses .env files to define the environment variables for the various packages. The .env files are
located in the root directory of the project and in the individual packages.
Please see for every package their .env.template file to see which variables are required. The .env files in the
root directory are also used to define the variables for the Docker containers.
=== Deployment
To deploy the project and run a production build, run the following commands:
If you already had a build before, use --build to force a rebuild:
==== Deploying using the GHCR (GitHub Container Registry) images 🐳
For every tag and release GitHub automatically builds a Docker image and pushes it to the GHCR. To use these images
simply run the following command (This will use the latest tag):
=== Accessing the Production Database
To access the production database, you will need to connect to the remote server with a set-up SSH tunnel, which allows you to access Adminer or the database locally as well.
If you have started the docker containers using the instructions in the previous section, then the ports will look like this:
Using that you can then setup the SSH tunnel using the following command:
ssh -L 8082:localhost:8082 -L 5432:localhost:5432 REMOTE_SSH_URL=== Testing
At the moment, tests are only implemented for @solardoc/asciidoc-renderer. This is expected to change by v0.3.0, but
at the moment only the renderer is tested.
To run the tests, run the following command:
== Is it any good?