DOCSEARCHbyAlgolia
Submit Docs

cflow

repository·main·Indexed 43 days ago

https://github.com/vespa314/cflow

A highly customized fork of memos version 0.18.2 optimized for personal use. It features enhanced editor capabilities (collapsible blocks, Mermaid syntax, Excalidraw support), advanced search macros, and data visualization tools like activity heatmaps and tag radiation diagrams. It is designed specifically for SQLite and includes a REST API for managing memos, authentication, and identity providers.

Tokens
16.3K
Snippets
72
Records
86
Agent score
55%

What's inside cflow

  1. Overview of cflow

    main

    cflow is a highly customized version of memos, developed based on the official version 0.18.2. It is designed as a personal tool for specific needs rather than a general-purpose open-source project.

    Important Limitations for Users:

    • Database Support: It only works correctly with SQLite. Other databases (like MySQL) are not supported due to the nature of the modifications.
    • Missing Features: The version available in this repository is the "memos main site" only. It does not include AI features (similarity recommendations, URL summaries, etc.), comments (Artalk), private sharing links, or advanced tag/card lineage, as these depend on an external Django backend and various microservices not included in this repo.
    • Language: Much of the UI text is hardcoded in Chinese and does not support multi-language versions.
    • Compatibility: It is compatible with the database from official version 0.18.2, but compatibility with other versions is not guaranteed.

  2. How API documentation is generated

    main

    The API documentation is automatically generated from Go source code comments using swaggo/swag. It follows the Declarative Comments Format.

    Key components:

    • Output Location: The generated documentation is stored in ./api/v1/docs.go.
    • Serving Documentation: The project uses echo-swagger to integrate with the Echo framework, serving the interactive Swagger-UI at http://memos.host:5230/api/index.html.

  3. Build Memos on Windows

    main

    When building Memos, the frontend must be built before the backend. The resulting frontend assets must be placed in the backend ./server/dist directory to avoid a "No frontend embeded" error.

    Frontend Build

    Run these commands from the project root to build the frontend and move the assets to the backend directory:

    Move-Item "./server/dist" "./server/dist.bak"
cd web; pnpm i --frozen-lockfile; pnpm build; cd ..;
Move-Item "./web/dist" "./server/" -Force

    Backend Build

    After the frontend assets are in place, build the backend executable:

    go build -o ./build/memos.exe ./bin/memos/main.go
    # Frontend build sequence
Move-Item "./server/dist" "./server/dist.bak"
cd web; pnpm i --frozen-lockfile; pnpm build; cd ..;
Move-Item "./web/dist" "./server/" -Force

# Backend build
go build -o ./build/memos.exe ./bin/memos/main.go

  4. Write API documentation comments in Go

    main

    Use the Declarative Comments Format to document your API endpoints. You can reference custom Go structs from outside the API file using relative definitions (e.g., store.User).

    Example of a standard API comment block:

    // signIn godoc
//
//  @Summary    Sign-in to memos.
//  @Tags       auth
//  @Accept     json
//  @Produce    json
//  @Param      body    body        SignIn      true    "Sign-in object"
//  @Success    200     {object}    store.User  "User information"
//  @Failure    400     {object}    nil         "Malformatted signin request"
//  @Failure    401     {object}    nil         "Password login is deactivated | Incorrect login credentials, please try again"
//  @Failure    403     {object}    nil         "User has been archived with username {username}"
//  @Failure    500     {object}    nil         "Failed to find system setting | Failed to unmarshal system setting | Incorrect login credentials, please try again | Failed to generate tokens | Failed to create activity"
//  @Router     /api/v1/auth/signin [POST]
func (s *APIV1Service) signIn(c echo.Context) error {
    ...
}

  5. Prerequisites for Memos development

    main

    To develop on Memos, you must have the following tools installed on your system:

    • Go: The backend language.
    • Air: Used for backend live reload.
    • Node.js: The runtime for the frontend.
    • pnpm: The package manager for the frontend.

  6. Format Protobuf files using buf

    main
    To automatically format the Protobuf files in the repository according to the project's style guidelines, use the buf format -w command. The -w flag writes the changes directly to the files.
    buf format -w

  7. Install memos as a Windows service using WinSW

    main

    WinSW (Windows Service Wrapper) allows you to run memos.exe as a service using an XML configuration file.

    Steps:

    1. Download the WinSW-net46x.exe asset from the WinSW releases.
    2. Place it in the same directory as memos.exe and rename it to memos-service.exe.
    3. Create a configuration file named memos-service.xml in the same directory.
    4. Run the install and start commands via PowerShell (as Administrator).

    Note: All commands require Administrator privileges.

    <!-- memos-service.xml -->
<service>
    <id>memos</id>
    <name>memos service</name>
    <description>A lightweight, self-hosted memo hub. https://usememos.com/</description>
    <onfailure action="restart" delay="10 sec"/>
    <executable>%BASE%\memos.exe</executable>
    <arguments>--mode prod --port 5230</arguments>
    <delayedAutoStart>true</delayedAutoStart>
    <log mode="none" />
</service>
    # Install the service
.\memos-service.exe install

# Start the service
.\memos-service.exe start

# Remove the service
.\memos-service.exe uninstall

  8. Install memos as a Windows service using NSSM

    main

    NSSM (Non-Sucking Service Manager) can be used as a lightweight wrapper to run memos.exe as a Windows service. The service will run under the SYSTEM account and start automatically at boot.

    Prerequisites:

    • Download the latest 64-bit version of nssm.exe.
    • Place nssm.exe in the same directory as memos.exe or add it to your system PATH.
    • All commands must be run with Administrator privileges.

    Steps:

    1. Install the service with specific arguments (e.g., production mode and port).
    2. (Optional) Set a display name, description, or delay the auto-start to prevent boot congestion.
    3. Start the service using NSSM or the Windows net command.
    # Install memos as a service
nssm install memos "C:\path\to\memos.exe" --mode prod --port 5230

# Configure service metadata
nssm set memos DisplayName "memos service"
nssm set memos Description "A lightweight, self-hosted memo hub. https://usememos.com/"

# Delay auto start
nssm set memos Start SERVICE_DELAYED_AUTO_START

# Start the service
nssm start memos

# Remove the service
nssm remove memos confirm

  9. Manage the memos Windows service

    main

    Once installed, you can manage the memos service using several methods:

    • Command Line: Use the standard Windows net command.
    • NSSM GUI: Use nssm edit memos to open a graphical configuration interface.
    • Windows Services Manager: Search for services.msc to manage the service via the standard Windows UI.
    • Troubleshooting: If the service fails to start, inspect the Windows Event Viewer (eventvwr.msc) for error logs.
    # Start the service
net start memos

# Stop the service
net stop memos

  10. Generate API documentation manually (no scripts)

    main

    If you prefer not to use the provided scripts, follow these steps to generate documentation using swag directly.

    1. Install Swag

    go install github.com/swaggo/swag/cmd/swag@latest

    Note: If $HOME/go/bin is not in your PATH, use the absolute path to the binary.

    2. Format comments

    swag fmt --dir ./api/v1 && go fmt

    3. Initialize documentation Run this from the project root:

    swag init --output ./api/v1 --generalInfo ./api/v1/v1.go --dir ./,./api/v1

    Note: If you add new API versions, you must update the --dir parameter to include the new file system paths.

  11. Update API documentation using provided scripts

    main

    To update the documentation after modifying API-related comments, run the project's built-in scripts. These scripts automatically install swag if necessary, run swag fmt, and then swag init.

    Linux:

    chmod +x ./scripts/gen-api-v1-docs.sh
./scripts/gen-api-v1-docs.sh

    Windows:

    ./scripts/gen-api-v1-docs.ps1
    ./scripts/gen-api-v1-docs.sh

  12. Set up the Memos development environment

    main

    Follow these steps to clone the repository and start both the backend and frontend development servers with live reload support.

    1. Clone the repository

    git clone https://github.com/usememos/memos

    2. Start the backend server

    Use air with the provided configuration to start the backend with live reload:

    air -c scripts/.air.toml

    3. Set up the frontend

    Navigate to the web directory, install dependencies, and generate the necessary TypeScript code from protobuf files:

    cd web && pnpm i && pnpm type-gen

    4. Start the frontend dev server

    Run the frontend development server:

    cd web && pnpm dev

    Once started, the application should be accessible at http://localhost:3001. Changes to either the frontend or backend code will trigger a live reload.

    # Full sequence
git clone https://github.com/usememos/memos
air -c scripts/.air.toml
cd web && pnpm i && pnpm type-gen
cd web && pnpm dev