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 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 💡

• Better code editor for writing AsciiDoc

• Better UI for viewing presentation slides and nested slides

• Ability to easily work collaboratively on presentations

• More accessibility for students and teachers

• Ability to share files with anyone using share links

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 ⚠️

• Conversion pipeline is too performance-heavy slowing down the browser of the user/client. (AsciiDoc → Presentation)

• The complexity of creating a presentation might get out of hand with big and detailed presentations.

Development 🛠

Setup

To set up the project please install PNPM and Node>=16. Then run the following commands:

pnpm install

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

• Frontend: pnpm run dev or pnpm run --filter @solardoc/frontend dev

• Rest-API: pnpm run start or pnpm run --filter @solardoc/rest-api start

The Redis DB is Docker-only and as such has to be started using the following command:

docker compose up -d redis-db

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:

docker compose up -d

If you already had a build before, use --build to force a rebuild:

docker compose up -d --build

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):

docker compose -f ./docker-compose.yaml -f ./docker-compose-prod.yaml up

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](#user-content-deploying-using-the-ghcr-github-container-registry-images), then the ports will look like this: - PostgreSQL: 5432 - Adminer: 8082

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:

pnpm run test

Is it any good?

Yes.