menu
MARKOPOLIS
Dark mode
Changelog
Installation
Markdown Syntax
Roadmap
Usage
Welcome to Markopolis

Installation

installation
docker
deployment

Installing Markopolis involves two steps.

  • STEP 1: Deploying the Markopolis server
  • STEP 2: Installing the Markopolis package on your local machine

STEP 1: Deploying Markopolis server

The easiest way to deploy the server is to use the provided docker image. The docker image packages both the backend and frontend together and sets up a reverse proxy to route requests correctly to the backend and frontend.

You can use the docker-compose provided below. Make sure to change the environment variables to match your settings.

Make sure to use a secure API key. You can use `openssl rand -hex 32` to generate a random alphanumeric string to use as your API key.

Docker Compose

version: '3.8'

services:
  markopolis:
    image: ghcr.io/rishikanthc/markopolis:0.2.0
    ports:
      - "8080:80"
    environment:
      - MARKOPOLIS_DOMAIN="https://your-domain.com"
      - MARKOPOLIS_FRONTEND_URL = https://your-domain.com"
      - MARKOPOLIS_TITLE="Awesome Notes"
      - MARKOPOLIS_MD_PATH=/app/markdown
      - MARKOPOLIS_API_KEY=<really long random alpha-numeric string>
    volumes:
      - markopolis_data:/app/markdown
    restart: unless-stopped

volumes:
  markopolis_data:
    driver: local
Parameter Description
MARKOPOLIS_DOMAIN This is the domain at which both your frontend and backend is available by default. Make sure to include the protocol along with your domain
MARKOPOLIS_FRONTEND_URL This parameter is available for configuring custom frontend implementations. If you are using the default front-end that ships with Markopolis, this should be same as MARKOPOLIS_DOMAIN.
MARKOPOLIS_TITLE This parameter controls the site title displayed on the top-left in the header
MARKOPOLIS_MD_PATH This is the path on the server at which your markdown files are stored. Ideally this should point to a directory in your persistent volume.
MARKOPOLIS_API_KEY For security, most of the API endpoints are protected by an API key. Make sure to use a secure API key and don't share it publicly.
the domains should not contain a leading slash at the end. For eg. https://example.com will work https://example.com/ will not work

STEP 2: Local installation

Markopolis provides an easy way to sync or push your markdown files from your computer to the server. You do not need to use Docker to mount your markdown files. Follow the instructions below to set this up.

I highly recommend configuring a virtual environment for python to keep your environment clean and and prevent any dependency issues. Below I detail the steps to do this using Conda or pip. If you are familar with this feel free to skip to the package installation section.

You need to have python version >= 3.11

Setting up a virtual environment

You can use either pip or conda to do this. If you are using pip simply run

python3.11 -m venv <name>

Replace <name> with your desired virtual environment name. You can then activate the virtual environment using:

source <name>

For conda, you can use

conda create -n <name> python==3.11

and activate it with

conda activate <name>

Package installation

Simply install the markopolis python package using your preferred package manager.

pip: 

pip install markopolis

Configuration

Create a yaml config file anywhere in your system to set the below values. I recommend storing it in .config/markopolis/settings.yaml.

You can name the file anything and you can store it anywhere. You will need to set the config path for Markopolis to read the config file correctly.

Point markopolis to your config file by setting the MARKOPOLIS_CONFIG_PATH to the location of your yaml file. You can also add it to your shell config so it persists across sessions.

bash or zsh (temporarily for current session) 

export MARKOPOLIS_CONFIG_PATH=/path/to/settings.yaml

bash or zsh (permanently for all sessions) 

echo 'export MARKOPOLIS_CONFIG_PATH=/path/to/settings.yaml' >> ~/.zshrc
echo 'export MARKOPOLIS_CONFIG_PATH=/path/to/settings.yaml' >> ~/.bashrc

source ~/.zshrc
source ~/.bashrc

fish (temporarily for current session) 

set -x MARKOPOLIS_CONFIG_PATH /path/to/settings.yaml

fish (permanently for all sessions) 

echo 'set -x MARKOPOLIS_CONFIG_PATH "/path/to/settings.yaml"' >> ~/.config/fish/config.fish
source ~/.config/fish/config.fish

Settings

Below is an example config:

default:
  domain: https://your-domain.com
  md_path: /path/to/markdown-notes
  api_key: <really long random alpha-numeric string>
Parameter Description
domain This should point to the markopolis backend deployed. Same value as MARKOPOLIS_DOMAIN from docker-compose.
md_path Local path to where your markdown notes are stored. This is the path on your local machine on which you have your obsidian notes stored.
api_key The API key you used when deploying the server. Same as MARKOPOLIS_API_KEY from docker-compose.

Testing deployment

Immediately after deployment, since no markdown files have been added, initially the site will throw an error. To test if the deployment was successful you can navigate to the API documentation page which is auto-generated and available at http(s)://your-domain.com/docs. This should display a swagger UI with details about all available API endpoints. It would look exactly like what's shown at Markopolis API docs

BACKLINKS