├── .env.example
├── .github
└── ISSUE_TEMPLATE
│ ├── bug.yml
│ └── config.yml
├── .gitignore
├── FAQs.md
├── README.md
├── config
└── nginx.conf
├── docker-compose.yml
├── gen-passwords.sh
└── setup.sh
/.env.example:
--------------------------------------------------------------------------------
1 | #
2 | # Frontend configuration.
3 | #
4 |
5 | # If the user should be required to login before doing anything.
6 | # Setting this to true will allow the user to "try out" the app without having to log in.
7 | OCULAR_DEMO=false
8 |
9 | #
10 | # Backend configuration.
11 | #
12 |
13 | # Database location
14 | GENESIS_DB_PATH=.data
15 |
16 | # JWT secret known only to your token generator
17 | GENESIS_JWT_SECRET=
18 |
19 | # JWT expiration in minutes
20 | GENESIS_JWT_TOKEN_EXPIRATION=120960
21 |
22 | # If the session cookie for the backend should be allowed to be sent over http
23 | # Dangerous, it's best to run it behind a reverse proxy with https
24 | GENESIS_JWT_COOKIE_ALLOW_HTTP=false
25 |
26 | # Gin mode, either test, release or debug
27 | GENESIS_GIN_MODE=release
28 |
29 | # Zap loggger, either production or development
30 | GENESIS_LOG_MODE=production
31 |
32 | # Port to listen on, leave it at 80 if you're using a reverse proxy
33 | GENESIS_PORT=80
34 |
35 | # Base url to listen for requests
36 | GENESIS_BASE_URL=/
37 |
38 | # Use ! as suffix for the username to indicate that this user
39 | # should be created as an admin. These can add, remove and edit users.
40 | GENESIS_CREATE_USERS=admin!:2lWK6m4hgmxjUGHo
41 |
42 | # Allowed username pattern
43 | GENESIS_USERNAME_PATTERN=^[\w]{0,32}$
44 |
45 | # Allowed key pattern
46 | GENESIS_KEY_PATTERN=^[\w]{0,32}$
47 |
48 | # Maximum size of each key in kilobytes
49 | GENESIS_DATA_MAX_SIZE=512
50 |
51 | # Maximum amount of datasets per user
52 | GENESIS_KEYS_PER_USER=2
53 |
--------------------------------------------------------------------------------
/.github/ISSUE_TEMPLATE/bug.yml:
--------------------------------------------------------------------------------
1 | name: Bug Report
2 | description: Report a bug in the docker setup for Ocular
3 | body:
4 | - type: checkboxes
5 | attributes:
6 | label: Support guidelines
7 | description: Please read the faqs before proceeding.
8 | options:
9 | - label: I've read the [FAQs](https://github.com/simonwep/ocular-docker?tab=readme-ov-file#faq)
10 | required: true
11 |
12 | - type: textarea
13 | attributes:
14 | label: Description
15 | description: Please provide a brief description of the bug in 1-2 sentences.
16 | validations:
17 | required: true
18 |
19 | - type: textarea
20 | attributes:
21 | label: Environment
22 | description: Please provide information about your environment.
23 | placeholder: |
24 | - Browser: [e.g. Chrome, Safari]
25 | - OS: [e.g. Windows, macOS]
26 | - Version: [e.g. 1.2]
27 | - Docker version: [e.g. 1.4]
28 | validations:
29 | required: true
30 |
31 | - type: textarea
32 | attributes:
33 | label: Expected behaviour
34 | description: Please describe precisely what you'd expect to happen. Be specific.
35 | validations:
36 | required: false
37 |
38 | - type: textarea
39 | attributes:
40 | label: Steps to reproduce
41 | description: Please describe the steps to reproduce the bug.
42 | placeholder: |
43 | 1. ...
44 | 2. ...
45 | 3. ...
46 | validations:
47 | required: false
48 |
49 | - type: textarea
50 | attributes:
51 | label: Additional info
52 | description: Please provide any additional information that seem useful.
53 |
--------------------------------------------------------------------------------
/.github/ISSUE_TEMPLATE/config.yml:
--------------------------------------------------------------------------------
1 | blank_issues_enabled: false
2 | contact_links:
3 | - name: Ask a question
4 | url: https://github.com/simonwep/ocular/discussions
5 | about: Please ask and answer questions here.
6 |
--------------------------------------------------------------------------------
/.gitignore:
--------------------------------------------------------------------------------
1 | .idea
2 | .env
3 | .env.bak
4 | data
--------------------------------------------------------------------------------
/FAQs.md:
--------------------------------------------------------------------------------
1 | # Frequently Asked Questions
2 |
3 | > [!NOTE]
4 | > Since this setup is fairly new, there might be some issues that are not covered here.
5 |
6 | This is a compilation of frequently asked questions and their answers.
7 | If you have a question that is not answered here, feel free to [open a discussion](https://github.com/simonwep/ocular-docker/discussions)!
8 |
9 | ## Table of Contents
10 |
11 | - [Where can I find the release notes?](#where-can-i-find-the-release-notes)
12 | - [I can't log in to the app over the network!](#i-cant-log-in-to-the-app-over-the-network)
13 | - [What kind of config do I need if I want to run it behind a nginx reverse proxy?](#what-kind-of-config-do-i-need-if-i-want-to-run-it-behind-a-nginx-reverse-proxy)
14 | - [I'm having troubles deploying it on Traefik](#im-having-troubles-deploying-it-on-traefik)
15 | - [Should I use nginx in the docker compose.yaml file if I already have my own reverse proxy already set up?](#should-i-use-nginx-in-the-docker-composeyaml-file-if-i-already-have-my-own-reverse-proxy-already-set-up)
16 | - [When reverse proxying Ocular, which Docker service do I point to: frontend, backend, or nginx?](#when-reverse-proxying-ocular-which-docker-service-do-i-point-to-frontend-backend-or-nginx)
17 |
18 | ## Where can I find the release notes?
19 |
20 | For release notes, check out the [latest release](https://github.com/simonwep/ocular/releases/latest) in the [ocular](https://github.com/simonwep/ocular) repository.
21 | This repo is just for production releases :)
22 |
23 | ## I can't log in to the app over the network!
24 |
25 | If you don't use https, make sure to set `GENESIS_JWT_COOKIE_ALLOW_HTTP` to `true` in your `.env` file.
26 | Otherwise, run it behind a reverse proxy like [nginx](https://www.nginx.com/) and get a free certificate from [letsencrypt](https://letsencrypt.org/).
27 |
28 | Make sure to restart the app after changing the `.env` file via `docker compose restart`.
29 |
30 | ## What kind of config do I need if I want to run it behind a nginx reverse proxy?
31 |
32 | Here's an example of a basic nginx config (v1.25+):
33 |
34 | ```nginx
35 | server {
36 | listen 443 quic reuseport;
37 | listen 443 ssl;
38 |
39 | server_name ocular.example.com;
40 | add_header Alt-Svc 'h3=":443"; ma=86400';
41 |
42 | location / {
43 | proxy_set_header X-Forwarded-Host $host;
44 | proxy_set_header X-Forwarded-Server $host;
45 | proxy_set_header X-Forwarded-Proto $scheme;
46 | proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
47 | proxy_set_header Host $host;
48 | proxy_read_timeout 300s;
49 | proxy_pass http://127.0.0.1:3030$request_uri;
50 | }
51 |
52 | # Specify the path to your certificate and key, or use letsencrypt
53 | #ssl_certificate
54 | #ssl_certificate_key
55 | }
56 |
57 | # HTTP Redirect
58 | server {
59 | listen 80;
60 | server_name ocular.example.com;
61 |
62 | if ($host = ocular.example.com) {
63 | return 301 https://$host$request_uri;
64 | }
65 |
66 | return 404;
67 | }
68 | ```
69 |
70 | ## I'm having troubles deploying it on [Traefik](https://traefik.io/traefik/)
71 |
72 | > As mentioned [here](https://github.com/simonwep/ocular-docker/issues/5#issuecomment-2535524284) of [#5](https://github.com/simonwep/ocular-docker/issues/5) by @CompeyDev.
73 |
74 | Required changes to make this work:
75 |
76 | 1. Backend (genesis) container:
77 | ```yml
78 | - "traefik.enable=true"
79 | - "traefik.http.routers.genesis.rule=Host(`ocular.example.com`) && PathPrefix(`/api`)"
80 | # Important: This is what took a bit to figure out; we want to remove the `/api` from the
81 | # request before forwarding it, otherwise the backend would get a request on `/api`, which
82 | # would not work, as it expects requests to / by default. An alternative would be to set
83 | # GENESIS_BASE_URL to `/api`
84 | - "traefik.http.middlewares.strip-prefix.stripprefix.prefixes=/api"
85 | - "traefik.http.routers.genesis.middlewares=strip-prefix"
86 | # The entrypoint and TLS here are mandatory, see https://community.traefik.io/t/different-container-behind-and-api-how/7622
87 | - "traefik.http.routers.genesis.entrypoints=https"
88 | - "traefik.http.routers.genesis.tls=true"
89 | - "traefik.http.routers.genesis.tls.certresolver=letsencrypt"
90 | - "traefik.http.routers.genesis.service=genesis-service"
91 | - "traefik.http.services.genesis-service.loadbalancer.server.port=3031"
92 | ```
93 |
94 | 2. Frontend (ocular) container:
95 | ```yml
96 | - "traefik.enable=true"
97 | - "traefik.http.routers.ocular.rule=Host(`ocular.example.com`)"
98 | - "traefik.http.routers.ocular.entrypoints=https"
99 | - "traefik.http.routers.ocular.tls=true"
100 | - "traefik.http.routers.ocular.tls.certresolver=letsencrypt"
101 | - "traefik.http.routers.ocular.service=ocular-service"
102 | - "traefik.http.services.ocular-service.loadbalancer.server.port=80"
103 | ```
104 |
105 | > [!NOTE]
106 | > Traefik prioritizes routers based on the length of the rule, so since the `genesis` router has a larger rule length, it matches `/api` requests first.
107 | > This is necessary as if the `ocular` router picked up requests, it would return 501 Unimplemented statuses (this is hardcoded).
108 |
109 | ## Should I use nginx in the docker compose.yaml file if I already have my own reverse proxy already set up?
110 | Yes, Ocular's nginx handles the _internal_ routing between the frontend and backend of Ocular.
111 | Your reverse proxy can be used to handle _external_ routing as usual.
112 |
113 | > As mentioned [here](https://github.com/simonwep/ocular-docker/discussions/11)
114 |
115 | ## When reverse proxying Ocular, which Docker service do I point to: frontend, backend, or nginx?
116 | Point your reverse proxy to Ocular's nginx, which in turn will handle routing between everything else.
117 | It may be helpful to use a `container_name` for Ocular's nginx to distinguish it from your own reverse proxy (e.g., `ocular-nginx`).
118 | If both your reverse proxy and Ocular are on the same docker network, you can use the container name `ocular-nginx` and its default internal port `80`, such as in the screenshot below (NPM):
119 |
120 | 
121 |
122 | > As mentioned [here](https://github.com/simonwep/ocular-docker/discussions/11)
123 |
--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
1 |
2 |
3 |