Paperwork

Paperwork -- 开源的笔记和存档软件,Evernote、Microsoft OneNote 和 Google Keep 等的自托管替代品。(Paperwork - OpenSource note-taking & archiving alternative to Evernote, Microsoft OneNote & Google Keep.)

Github星跟蹤圖

Paperwork

Paperwork 是 Evernote®、Microsoft OneNote® 或 Google Keep® 等服务的开源、自托管替代品。

版本2

该分支包含 Paperwork 的第二个迭代,这是一个完整的重写。它不仅基于另一个框架 -- 而且基于完全不同的技术堆栈。它处于非常早期的开发阶段,还不能使用。

如果您正在寻找基于 Laravel 的 Paperwork 版本1,请查看 此分支。版本1不再处于活动开发阶段了!

我很乐意帮助构建v2!请随意查看此分支,并参与已有的内容,以了解Paperwork的发展方向。还要查看 当前的问题,看看需要做什么或建议在未来的迭代中可以做些什么。

此外,您可以加入 官方聊天室 并参加那里。

信息:99%的操作发生在其他存储库中!这个存储库只包含一键部署的 Paperwork!

Spoiler(剧透)

为了使 Paperwork 于当前运行状态(正在开发中),您必须了解 Docker 和 DNS 的工作原理并了解 HTTP 代理的基本概念。此外,于 Traefik 和 Minio 的经验可能会派上用场。

如果你没有这些,那么目前的 Paperwork 可能并不适合你。需要说明的是:这个软件现在不能用。它正在研制中,不久的将来就能投入使用。在目前的状态下,document v2 的目标是那些希望亲自动手并为项目做出贡献的开发人员。

演示

有关当前 Paperwork 状态的演示,请访问 http://www.demo.paperwork.cloud (抱歉,还没有 HTTPS!)。此实例不会在服务器端保留数据,但会将其缓存在浏览器会话中。该实例每天晚上凌晨1点被销毁。因此,所有帐户仅在最多一天有效。请不要使用此实例来存储实际数据/敏感信息!

该演示实例由 twostairs 赞助。

建立

这个存储库正在组织和统一所有 Paperwork 所需的组件。它的目的是提供一个例子,说明如何自己托管 Paperwork。但是,请记住,这个存储库中使用的堆栈文件不应该用于实际的、面向 internet 的部署,因为它缺乏以安全的方式管理服务之间凭证的能力。

$git clone git@github.com:paperwork/paperwork.git

Docker Stack

为了轻松地将 Paperwork 作为 Docker 堆栈运行,使用您喜欢的任何编排器,这个存储库附带了一个方便的 Makefile。我们来看看它:

$make help

部署

启动 Paperwork 可以通过制作 deploy`target 来完成:

$ make deploy

然后 Makefile 负责初始化 Swarm,如果你还没有这样做,创建加密网络(papernet)并在其上部署 Paperwork 堆栈。

概覽

名稱與所有者paperwork/paperwork
主編程語言Shell
編程語言Makefile (語言數: 2)
平台Docker, Linux, Unix-like
許可證GNU Affero General Public License v3.0
發布數2
最新版本名稱snapshot-3751d936 (發布於 )
第一版名稱snapshot-9f0655b (發布於 )
創建於2014-07-03 13:42:20
推送於2022-07-10 16:38:15
最后一次提交2022-07-10 11:38:15
星數7.9k
關注者數294
派生數662
提交數1.5k
已啟用問題?
問題數578
打開的問題數32
拉請求數299
打開的拉請求數0
關閉的拉請求數47
已啟用Wiki?
已存檔?
是復刻?
已鎖定?
是鏡像?
是私有?

Paperwork

Paperwork is an open-source, self-hosted alternative to services like Evernote ®, Microsoft OneNote ® or Google Keep ®

Version 2

This branch contains the second iteration of Paperwork, which is a complete rewrite. Not only is it based on another framework - it is based on a completely different technology stack. It is in its very early development phase and not yet usable.

If you were looking for the Laravel-based version 1 of Paperwork, please check out this branch. Version 1 is not in active development anymore!

I would love to help building v2!

Feel free to check out this branch and get involved with what's there already to get an idea of where Paperwork is heading. Also check out the current issues to see what needs to be done or suggest what could be done in future iterations.

Also, you can join the official chatroom and participate there.

Info: 99% of the action happens inside the other repositories! This repository only contains of the one-click-deployment of Paperwork!

Spoiler

In order to get Paperwork in its current state (under development) running, you have to have an understanding for how Docker and DNS works and know the basic concepts of HTTP proxying. Also, experience with Traefik and Minio might come in handy.

If you don't have that, then the current state of Paperwork probably isn't for you in first place. To make it clear: This software is not usable at this moment. It's being worked on to be made usable in the near future. In its current state, Paperwork v2 is targeted to developers that would like to get their hands dirty and contribute to the project.

Demo

A demo of the current Paperwork status is available at http://www.demo.paperwork.cloud (sorry, no HTTPs yet!). This instance won't persist data on the server side, but it does cache it inside your browser session. The instance is being destroyed every night at 1am UTC. Therefor all accounts are only valid for maximum one day. Please do not use this instance to store actual data/sensitive information!

This demo instance is sponsored by twostairs.

Setup

This repository is structuring and unifying all required components for Paperwork. It its purpose is to provide an example of how you could host Paperwork yourself. However, please keep in mind that the stack file used in this repository should not be used for real-world, internet-facing deployments, as it lacks the ability to manage credentials between services in a secure manner.

$ git clone git@github.com:paperwork/paperwork.git

Docker Stack

In order to easily get Paperwork running as a Docker stack, utilising whichever orchestrator you'd like, this repository comes with a handy Makefile. Let's have a look at it:

$ make help

Deploy

Launching the Paperwork can be done by make-ing the deploy` target:

$ make deploy

The Makefile then takes care of initialising Swarm, in case you haven't done that already, creating the encrypted network (papernet) and deploying the Paperwork stack on top of it.

Configuration

This Docker stack is configured to use www.paperwork.local (for the web UI) and api.paperwork.local (for the API services) by default. Hence you will need to add these to the 127.0.0.1 entry in your /etc/hosts file:

127.0.0.1   localhost paperwork.local api.paperwork.local www.paperwork.local

If you'd want to use a different domain and different hostnames for web and API, make sure to export the following env variables:

  • PAPERWORK_API_PROTOCOL (http by default, https also possible)
  • PAPERWORK_API_HOSTNAME (api by default)
  • PAPERWORK_WEB_HOSTNAME (www by default)
  • PAPERWORK_DOMAIN (paperwork.local by default)

In addition to these variables, you can also use the following ones to override a couple of other defaults:

  • PAPERWORK_JWT_SECRET (the JWT secret used by service_gatekeeper and service_users)

Undeploy

In order to stop/remove the whole stack, simply use the undeploy target:

$ make undeploy

Note: This won't make your Docker host leave Swarm again, in case it wasn't running in Swarm mode before deploying! If you'd like to turn off Swarm, you have to manually do so.

Orchestrator

If you'd like to use a different orchestrator for stack deployment, you can do so by setting the ORCHESTRATOR variable on deploy:

$ make deploy ORCHESTRATOR=kubernetes

For more info, check the official Docker documentation for Mac and Windows.

Usage

As soon as you've finished the setup, you should be able to access your Paperwork deployment through this URL and you should be greeted with the login/registration:

Welcome to Paperwork

In order to use Paperwork, you will need to register a new account.

Developing / Contributing

Please refer to the individual services' repositories in order to get more information on how to contribute.

Repositories

Here are the main repositories of Paperwork v2:

  • paperwork: This repository, containing the one-click-deployment and overall documentation
  • paperwork.ex: Elixir SDK for building Paperwork services
  • service-gatekeeper: Gatekeeper service built in Rust, that reverse-proxies requests to individual services and takes care of JWT validation/decoding
  • service-configs: Configurations service built in Elixir, that stores instance configs and provides them through an internal endpoint to other services
  • service-users: Users service built in Elixir, that stores user information and provides endpoints for users to register, login and update their information
  • service-notes: Notes service built in Elixir, that stores all user's notes
  • service-storages: Storages service built in Elixir, that stores all user's attachments
  • service-journals: Journals service built in Elixir, that stores events related to database changes inside journals in order to provide information about these changes to the API clients
  • web: Angular 7-based web front-end for Paperwork

Paperwork Architecture

Paperwork Architecture

Description

The Paperwork project consists of a handful of custom-built API services, which take care of everything related to their specific domain: Configurations, users, notes & attachments. Underneath those, there are various infrastructure services which are either implemented by the Paperwork project (service-gatekeeper) or simply awesome third-party open-source projects that's being made use of (e.g. Minio and Traefik).

The API services provide the core logic that processes domain specific data and persists it on the service's own database. Each API service has its own database that no other services accesses directly. Instead, services communicate with each other through internal HTTP endpoints. The gatekeeper service abstracts the authorisation layer from each individual service by checking and decoding the JWT bearer, so that every service that runs behind service-gatekeeper can be sure that access was validated and session information is forwarded and accessible via HTTP headers. JWT crafting is currently done in service-users. Hence, service-gatekeeper and service-users need to share the same JWT secret. Implementation in this area is kept simple for now but will change with the introduction of OAuth 2.

While the API services are not exchangeable, infrastructure services usually are. For example Traefik could be replaced with NGINX, Minio with a real Amazon S3 storage and even gatekeeper could more or less easily be replaced with Kong or a similar API gateway in future. API services on the other hand are tightly integrated with the business logic and their own databases. Also, because they exchange information with each other through internal endpoints, they depend on each other and (partially) on their peer's data structures. For example the notes service performs an internal request towards the users service when a note is being requested, in order to include user information (first name, last name, etc) for every access definition within that note. This aggregation of data is not necessary form a back-end point of view and is only done in order to make things more comfortable for the UI layer. While, from a separation-of-concerns-perspective this might not be an ideal setup, it reduces complexity for now and allows the project to iterate quite quickly.

On top of the infrastructure and API services there is the UI layer that was just mentioned, which currently consists of the Paperwork Web UI. The web UI is a PWA built on Angular 7 that talks to the API services through the gatekeeper service. It's aimed to provide 100% offline use capabilities, so that it can be worked with in scenarios in which there's no connectivity to the API.

Local development environment

This repository not only features a one-click Docker Stack deployment, but also a local development environment which should work on any Linux/Unix platform. The goal is to provide you with a way to easily run an environment you can use to develop on individual services or UIs.

Using the local dev env

In order to launch the local development environment, simply utilise the same make command you use for running local development instances for each Paperwork service: make local-run-develop

$ cd paperwork/
$ make local-run-develop

The local dev env will start up with a short info on what's needed in order for it to function correctly. Please read the instructions provided there and follow them carefully. You will need to have some dependencies (e.g. Docker, Caddy) ready to use in order for the local dev environment to function.

Also make sure to have the following TCP ports free on your system while using the local dev env:

Optionally, if you plan to run any of the following services, you'll need to make sure to have their local dev env ports free as well:

Check this video (38MB) in order to see how easy it is to get your local development up and running with make local-run-develop.

Tasks/Issues

As for now, all tasks/issues are being collected inside this repository, just to keep it simple. On a long term, tasks/issues will be transferred into the related service's repository, in order to be able to reference them through git commits.

Donating

The best way to help this project is by contributing to the code. However, if that should not be possible to you, but you'd still like to help, the Paperwork project gladly accepts donations in form of Bitcoins and Ether. Please use the following addresses to direct your donations:

Ethereum: 0x8Ea80Ab7eD3e925BdF1975F5afEb6bcA23C6581a

0x8Ea80Ab7eD3e925BdF1975F5afEb6bcA23C6581a

Bitcoin: 3DzwbsXp53VhANzF3jF2ch28Qnv1BeX1jk

3DzwbsXp53VhANzF3jF2ch28Qnv1BeX1jk

CAUTION: Do not send any donations to anywhere else but those addresses. Unfortunately we had situations in which random people (that were not affiliated with this project in any kind) posted PayPal addresses inside GitHub issues in order to scam money.

去到頂部