Introducing a new way to review your PRs.

Read the announcement

usememos / memos

Memos is an open-source, self-hosted note-taking app that brings your everyday thoughts together in a personal timeline. Your data stays yours, and you choose what to keep private or share.

View on GitHub

25 documents · Updated Nov 20, 2026

docs / deployment-configuration-and-operations

Deployment, configuration, and operations

Memos is a self-hosted note service that runs as one process or one container. A deployment gives the process its listener, data store, external URL, and optional secret-backed settings. The process then prepares persistent state, applies declarative instance settings, serves the web and API surfaces, and shuts down cleanly on a stop signal.

Deployment model

Memos supports a small deployment footprint without giving up support for external databases. The same server binary runs in a native environment or in the published container image.

Deployment forms

The main deployment choices are:

FormOperational rolePersistent state
Docker imageSimple and repeatable production or local deploymentA volume mounted at /var/opt/memos
Native binaryDirect installation on Linux or macOSThe configured data directory
Docker ComposeA small declarative wrapper around the imageThe host directory mapped to /var/opt/memos

The image exposes port 5230 and uses UTC by default. A native process uses port 8081 unless its port is changed. In both cases, the data store and configuration rules are owned by the same Memos process. (/home/user/repo/scripts/Dockerfile#L29-L57, home/…/compose.yaml• L1-8, home/…/main.go• L59-77)

References: home/…/README.md• L17-22 home/…/Dockerfile• L29-57 home/…/compose.yaml• L1-8

Development proxy

The frontend development server provides a local browser endpoint and forwards API, event-stream, RPC, and file requests to a Memos backend. DEV_PROXY_SERVER selects the backend target. Without it, the proxy uses http://localhost:8081. The proxy uses the current /api route shape, so local frontend work follows the same API paths as the running service.

References: home/…/vite.config.mts• L7-38

Startup lifecycle

Startup turns deployment inputs into a working service. Persistent state is prepared before request handlers are created, so the first request sees the selected schema and the effective declarative configuration. See server runtime and request routing for the request paths that run after startup.

Startup stages

The following flow shows how a deployment becomes a ready Memos service.

flowchart TD
    Inputs[Flags and MEMOS environment] --> Profile[Validate runtime profile]
    Profile --> Database[Open selected data store]
    Database --> Schema[Initialize or migrate schema]
    Schema --> Config[Load and apply declarative configuration]
    Config --> Server[Build shared HTTP server]
    Server --> Listener[Open TCP listener or Unix socket]
    Listener --> Ready[Serve health, web, API, file, RSS, and MCP requests]
    Ready --> Stop[Receive interrupt or SIGTERM]
    Stop --> Shutdown[Close long-lived work, HTTP, and database]

The process validates the profile first. It then opens SQLite, MySQL, or PostgreSQL, runs schema work, applies the configuration directory, and constructs the server. A failure in an early stage prevents the service from accepting traffic. Demo content is seeded after configuration, so it can attach to users declared by that configuration. (home/…/main.go• L119-200, home/…/server.go• L49-105)

The black-box startup checks follow the same sequence as the serving process. They verify readiness, fresh installation, restart with retained data, demo startup, and configuration applied before requests are served. (home/…/startup_test.go• L69-130, home/…/startup_test.go• L352-394, home/…/startup_test.go• L542-595)

References: home/…/main.go• L119-200 home/…/main.go• L261-304 home/…/server.go• L39-93 home/…/server.go• L96-142 home/…/startup_test.go• L69-130

Runtime configuration

Runtime configuration controls how the process listens, where it stores data, which database it uses, how it identifies the public instance, how it applies declarative files, and which private network destinations webhooks may reach. Command-line flags and MEMOS_ environment variables provide the process-level settings.

Process settings

Viper maps flag names to environment names by replacing hyphens with underscores. For example, --instance-url maps to MEMOS_INSTANCE_URL, and --log-level maps to MEMOS_LOG_LEVEL. Flags and environment values feed one runtime profile.

SettingDefault or ruleOperational effect
driver / MEMOS_DRIVERsqliteSelects the database backend; startup currently accepts sqlite, mysql, or postgres
port / MEMOS_PORT8081 in the binary; 5230 in the imageSets the TCP port
addr / MEMOS_ADDREmptyBinds the TCP listener address
unix-sock / MEMOS_UNIX_SOCKEmptyUses a Unix socket and overrides address and port
data / MEMOS_DATAWritable /var/opt/memos when available; otherwise the current directorySelects the local data directory
dsn / MEMOS_DSNDerived SQLite file or supplied database source nameIdentifies the database connection
instance-url / MEMOS_INSTANCE_URLEmptySets the canonical external URL
log-level / MEMOS_LOG_LEVELinfoSets log filtering to debug, info, warn, or error
demo / MEMOS_DEMOfalseEnables SQLite demo data and demo behavior
config-dir / MEMOS_CONFIG_DIR/etc/memos/configSelects the JSON configuration directory
config-apply / MEMOS_CONFIG_APPLYstartupApplies configuration at startup; off leaves application to memos config apply
webhook-private-network-allowlist / MEMOS_WEBHOOK_PRIVATE_NETWORK_ALLOWLISTEmptyAllows only listed private webhook destinations
allow-private-webhooks / MEMOS_ALLOW_PRIVATE_WEBHOOKSfalse; deprecatedDisables private-network protection for compatibility
rate-limit / MEMOS_RATE_LIMITtrueEnables request rate limiting
trusted-proxies / MEMOS_TRUSTED_PROXIESprivateSelects which proxies may identify the client through forwarding headers; none disables proxy trust

The canonical instance URL must use HTTP or HTTPS and must have a host. Memos removes trailing slashes but rejects credentials, queries, and fragments. The URL identifies the external service. Its presence no longer serves as the lasting access-policy setting after the access setting is initialized. (home/…/main.go• L56-77, home/…/profile.go• L64-151, home/…/migrator.go• L142-161)

The private webhook allowlist accepts exact host names, IP addresses, or CIDR ranges. The deprecated global setting remains available for older deployments, but it removes the protection that the allowlist provides. The rate limit and trusted-proxy settings affect request handling after startup. Trusted proxy rules control which forwarding headers can supply the client address used by request controls. (home/…/main.go• L71-77, home/…/main_test.go• L19-29, home/…/server.go• L55-64)

References: home/…/main.go• L56-107 home/…/profile.go• L15-41 home/…/profile.go• L64-151 home/…/server.go• L55-64

Declarative configuration files

Declarative configuration describes instance resources in JSON files. Memos loads every regular .json file in MEMOS_CONFIG_DIR, resolves ${env:NAME} and ${file:/absolute/path} values, validates the merged desired state, and records which file owns each resource. The default directory is /etc/memos/config.

The configuration surface covers identity providers, selected instance settings, and users. A missing directory is an empty desired state. Validation reports all file problems together, while an apply compares the desired state with the database and shows resource changes before writing them. See declarative configuration management for the file schema and ownership rules.

The command-line workflow separates inspection from mutation. Configuration command flags override their environment and default values. Read-only commands do not create or migrate a database; apply performs the same database preparation as server startup.

CommandDatabase behaviorOperational use
memos config validateDoes not open a databaseCheck file shape and values
memos config planReads an existing database without creating or migrating itPreview changes; --detailed-exitcode returns 2 when changes exist
memos config applyCreates a new database or migrates it as server startup doesApply the plan and state record in one transaction
memos config stateReads the stored state recordInspect managed resources and the last apply

Startup applies the same desired state by default after migration and before the listener starts. Operators can run memos config apply as a separate job and set --config-apply=off on the serving replicas. This makes configuration rollout explicit while keeping every replica's ownership checks tied to the database state. (home/…/config.go• L93-125, home/…/config.go• L208-245, home/…/main.go• L261-304)

References: home/…/configuration.go• L1-10 home/…/configuration.go• L25-128 home/…/decode.go• L33-61 home/…/config.go• L33-109 home/…/config.go• L160-269 home/…/main.go• L261-304

Legacy deployment files

Older Memos releases accepted identity-provider and instance-setting JSON files in /etc/secrets. Current startup does not read those files or import them. If matching legacy files remain, startup lists them in a warning and points the operator to MEMOS_CONFIG_DIR; the files must be declared there instead.

This warning is informational. It does not open or apply the legacy files, so keeping them mounted cannot change the running instance's settings. See declarative configuration management for the active file format and ownership rules.

References: home/…/main.go• L167-172 home/…/main.go• L317-350

Configuration transactions and ownership

An apply computes a plan and writes resource changes plus the configuration state record in one transaction. The state stores the serial, configuration digest, apply metadata, source file, managed fields, ignored fields, and resource references. A failed plan or write leaves the instance unchanged.

The API reads this state from the database on every replica. An administrator can inspect it through the configuration status endpoint. A direct API write that changes a managed field, creates or deletes a managed resource, or renames a user named by a managed usage-limit rule is rejected with a failed-precondition error. Fields released by ignoreChanges remain available to the API.

Configuration ownership also affects secrets. Storage secrets, SMTP passwords, AI provider keys, and identity-provider client secrets are not returned in API responses. An empty write-only secret in an update means “keep the stored value” rather than “clear it.”

References: home/…/apply.go• L20-74 home/…/guard.go• L13-74 home/…/instance_service_configuration.go• L23-119 home/…/instance_service.go• L202-327 home/…/instance_service_converters.go• L13-41 home/…/idp_service.go• L136-168

Resource identity and provisioning

Configuration uses public resource names as stable identities across files and applies. Identity providers use identity-providers/{uid}, instance settings use instance/settings/{KEY}, and users use users/{username}. Usage-limit rules refer to users by these names, so a named user must exist before the setting can be applied.

An identity-provider sign-in first links an existing external subject when one is known. If no link exists, Memos can provision a local user when registration is allowed. It uses a valid external identifier as the initial username when possible and otherwise generates a UUID username. A malformed or already-used provider email is not assigned to the new account.

References: home/…/schema.go• L18-67 home/…/plan.go• L268-349 home/…/resource_name.go• L20-71 home/…/user_resource_name.go• L11-38 home/…/auth_service_sso.go• L21-191 home/…/sso_username.go• L10-22

Secret-backed database settings

The container entrypoint supports MEMOS_DSN_FILE as a file form of MEMOS_DSN. Exactly one of the direct value and file value may be set. The entrypoint reads the file, exports the resulting MEMOS_DSN, removes the helper variable, and starts Memos. This keeps a database connection string out of the main container command line while preserving the same application setting.

References: home/…/entrypoint.sh• L24-52 home/…/entrypoint_test.sh• L30-113

Persistence and database operation

Memos separates the process profile from persistent application state. SQLite normally stores a production database as memos_prod.db or a demo database as memos_demo.db in the data directory. External database modes use the supplied DSN. The store layer and its data model are described in persistence and data evolution.

Database selection

The database driver factory selects one of three supported backends. SQLite uses local files and enables settings intended to reduce lock problems. MySQL and PostgreSQL use network connection strings supplied by the deployment. Demo mode is restricted to SQLite because its seed data is local and built for that backend. (home/…/db.go• L13-31, home/…/profile.go• L71-117, home/…/sqlite.go• L21-60, home/…/mysql.go• L20-40, home/…/postgres.go• L21-40)

References: home/…/db.go• L13-31 home/…/profile.go• L60-117 home/…/sqlite.go• L21-60 home/…/mysql.go• L20-40 home/…/postgres.go• L21-40

Schema lifecycle

At first use, Memos creates the latest schema for the selected backend. On later starts, it compares the stored schema version with the version supported by the binary and applies the needed incremental migrations. Migration work runs as a unit, and the stored schema version advances only after success.

The migrator also preserves a guarded upgrade path for very old installations. A database below the supported version floor must first pass through the required intermediate release. See database provisioning and migrations for the backend setup and migration lifecycle.

References: home/…/migrator.go• L22-43 home/…/migrator.go• L99-139 home/…/migrator.go• L164-233 home/…/migrator.go• L236-277 home/…/migrator.go• L396-438

Container and entrypoint behavior

The container is a small runtime image around the Memos binary. It treats /var/opt/memos as the writable data volume and starts with root only long enough to repair volume ownership before dropping to the configured runtime identity.

Container runtime

The image builds the Go binary and copies the release frontend assets into the server image. It uses Go 1.27.4 for the backend build and Alpine 3.21 for the runtime image. It creates a non-root user with UID and GID 10001, sets UTC, exposes 5230, and uses the data volume as its working directory. The image entrypoint passes its command to the Memos binary after its setup work.

Release and local image builds must provide a VERSION build argument. The Docker build embeds that value and the supplied commit in the binary, so a container image has an explicit release identity rather than relying on build-time defaults. (/home/user/repo/scripts/Dockerfile#L17-L27)

References: home/…/Dockerfile• L1-27 home/…/Dockerfile• L29-57

Entrypoint privileges

The entrypoint uses MEMOS_UID and MEMOS_GID to select the process identity. When it starts as root, it attempts to assign the data volume to that identity and then re-executes itself as the target user. A marker prevents a root target, which is useful in rootless Docker setups, from causing a re-exec loop.

References: home/…/entrypoint.sh• L3-22 home/…/entrypoint_test.sh• L16-41

Release and version operation

Release work produces matching frontend and backend artifacts, labels the binary with release identity, and checks that a new image works both on a fresh volume and on data from the previous stable release.

Build artifacts

The frontend release command writes static assets to the server's frontend distribution path. The container build then compiles the backend with the Go 1.27.4 toolchain and a version and commit supplied as build arguments. The module declares Go 1.27.0 as its language baseline. A direct local Go build can still produce a development binary without release metadata, but the container build requires an explicit version.

The release workflow packages native binaries for Linux, macOS, and Windows across its supported CPU targets. It also builds multi-architecture Linux images. Checksums accompany the binary archives so native installs can verify their downloads. (home/…/release.yml• L65-194, home/…/release.yml• L228-356)

References: home/…/package.json• L8-17 home/…/Dockerfile• L15-27 home/…/build.sh• L20-32 home/…/go.mod• L1-4 home/…/release.yml• L18-22 home/…/release.yml• L65-194 home/…/release.yml• L228-356

Version identity

Release builds embed the application version and source commit. A development binary reports dev and unknown when those values are not supplied. The memos version command, --version, and -V report the same application version without starting the server. The application version and the stored database schema version are related release concerns but are not the same value.

Release tags use YY.MM.N and -rc.N forms. Bare YY.MM values are image aliases that follow the newest stable release in that month. Stable releases publish a version tag, a series tag when needed, and the stable image tag. Release candidates publish only their candidate tag. A development image version comes from the commit date in UTC. The release scripts select the newest stable ancestor as the upgrade baseline and retain v0.31.x as the legacy baseline. Database migration sequences remain separate from application release tags.

The release script and the binary validate the same accepted version set. This prevents a tag from producing an artifact that refuses to start. The version flag uses -V as its short form, while the version subcommand and --version print the same line. (home/…/version.go• L10-18, home/…/main.go• L46-52, home/…/main.go• L108-114, home/…/main_test.go• L31-66, /home/user/repo/scripts/Dockerfile#L17-L27, home/…/migrator.go• L324-367, home/…/release_version.sh• L5-97, home/…/release_version_test.go• L15-99)

References: home/…/version.go• L10-18 home/…/main.go• L46-52 home/…/main.go• L108-114 home/…/main_test.go• L31-66 home/…/release_version.sh• L5-105 home/…/release_version_test.go• L15-113

Release pipeline

The release workflow treats the upgrade smoke check as a gate before it builds release artifacts. A calendar release tag starts version extraction, frontend and binary builds, checksum creation, GitHub release publication, and multi-architecture image publication. A manual run can build and inspect artifacts without publishing a GitHub release or container image.

The workflow needs the full tag history when it prepares a release. This lets the version script find the previous stable release for release notes and upgrade checks. Native artifacts cover Linux, macOS, and Windows. Release images cover linux/amd64, linux/arm/v7, and linux/arm64. Stable images receive the release version, its series when different, and stable; release candidates receive only the candidate tag. (home/…/release.yml• L3-63, home/…/release.yml• L87-225, home/…/release.yml• L228-356)

References: home/…/release.yml• L3-63 home/…/release.yml• L65-225 home/…/release.yml• L228-356 home/…/release_version.sh• L55-97

Canary image pipeline

Pushes to main build a canary image without creating a GitHub release. The pipeline builds the frontend first, derives a calendar version from the commit date, builds separate linux/amd64 and linux/arm64 images, and merges their digests into the canary tag in Docker Hub and GitHub Container Registry.

The canary path uses the same container build contract as a release path, including the embedded version and commit. Its purpose is to make the current main branch available for image-level checks or early use without changing stable release tags.

References: home/…/build-canary-image.yml• L1-13 home/…/build-canary-image.yml• L14-49 home/…/build-canary-image.yml• L51-123 home/…/build-canary-image.yml• L125-161

Release smoke checks

The release smoke script checks a candidate Docker image as a black-box release. It can build the current worktree or test an existing image, then verifies both a fresh install and an upgrade from a previous stable image. When no previous image is given, the script selects the latest supported stable Git tag before the current revision.

The fresh-install check confirms that the web assets load, an administrator can sign in, and a memo survives a container restart. The upgrade check creates data with the previous image, starts the candidate against the same volume, and confirms that old data remains usable while new data can be written. The script detects the current /api root and falls back to /api/v1 for older stable images, so the upgrade check can compare releases across the API route change. It waits for /healthz before each check and prints container logs when readiness fails.

The script needs Docker, curl, git, and jq; a local candidate also needs pnpm. It uses temporary containers and volumes by default, then removes them and restores any local frontend index that it replaced. --keep-resources or MEMOS_SMOKE_KEEP_RESOURCES=1 preserves the test resources for debugging. The release workflow runs this check before artifact publication. The upgrade workflow also runs it for relevant pull requests, together with database upgrade checks for SQLite, MySQL, and PostgreSQL and entrypoint secret tests. (home/…/upgrade-smoke.yml• L11-93)

References: home/…/release_smoke_test.sh• L17-41 home/…/release_smoke_test.sh• L80-92 home/…/release_smoke_test.sh• L115-207 home/…/release_smoke_test.sh• L221-247 home/…/release_smoke_test.sh• L249-262 home/…/release_smoke_test.sh• L264-305 home/…/release_smoke_test.sh• L307-350 home/…/upgrade-smoke.yml• L42-93

Continuous integration checks

Pull requests and pushes to main use separate backend and frontend checks to catch code, route, and asset regressions before release work. Backend checks verify module and source hygiene, lint the Go code, and run grouped tests for the store, server, internal packages, and other Go packages. The server group boots the real server and checks its mounted routes. Coverage uploads occur for main-branch pushes.

Frontend checks run linting, unit tests, and a production build. These checks run when web code, their setup action, or the workflow changes. The release and canary pipelines then reuse the release frontend output when they build deployable artifacts. (home/…/backend-tests.yml• L3-88, home/…/frontend-tests.yml• L3-48)

References: home/…/backend-tests.yml• L3-88 home/…/frontend-tests.yml• L3-48

Binary installation

The native installer selects Linux or macOS and the supported CPU architecture, downloads a versioned release archive, verifies its checksum when available, and installs the memos binary. It uses the latest release when no version is given and accepts a pinned version with or without a leading v.

The installer uses /usr/local/bin when it can write there or can use sudo. Otherwise it falls back to $HOME/.local/bin. It supports calendar releases and the legacy v0.31.x tag form. Operators can select another repository or install directory, skip checksum verification, or reduce output through command-line flags or environment variables. (home/…/install.sh• L5-29, home/…/install.sh• L48-63, home/…/install.sh• L98-115, home/…/install.sh• L137-171, home/…/install.sh• L200-235, home/…/install.sh• L237-296)

References: home/…/install.sh• L5-29 home/…/install.sh• L48-63 home/…/install.sh• L98-115 home/…/install.sh• L137-171 home/…/install.sh• L200-235 home/…/install.sh• L237-296 home/…/install_test.go• L15-79

Logging and operational defaults

Memos exposes a small set of operational signals for supervisors and operators. Logs describe startup and failure conditions, /healthz reports service readiness, and shutdown gives active work a bounded time to finish.

Log output

The process configures a text slog logger on standard error. The log level accepts debug, info, warn, and error without case sensitivity. An invalid value produces a warning and uses info, which prevents a bad verbosity setting from hiding normal operational events.

Startup also prints a short greeting with the version, data directory, database driver, listener, and access mode. These values help an operator confirm that the process received the intended deployment settings. Secret values are not part of the startup summary.

References: home/…/log.go• L11-28 home/…/main.go• L29-35 home/…/main.go• L215-243

Listener and readiness

The server listens on TCP unless MEMOS_UNIX_SOCK is set. A Unix socket overrides the TCP address and port and receives mode 0660. The /healthz endpoint returns success after the server is serving requests, which gives container and release checks a simple readiness probe.

References: home/…/server.go• L78-81 home/…/server.go• L108-141 home/…/release_smoke_test.sh• L190-224

Shutdown behavior

On interrupt or SIGTERM, Memos closes long-lived server-sent event connections, drains ordinary HTTP work, and closes the store. The HTTP shutdown window is ten seconds. If graceful shutdown fails, the server uses a forceful close path and logs the failure.

References: home/…/main.go• L188-200 home/…/server.go• L27-28 home/…/server.go• L144-177

Safety defaults

An instance with no canonical external URL starts with private access after the access policy is initialized. Webhook delivery blocks private and reserved network destinations unless an operator provides a narrow allowlist. The older global private-webhook flag remains for compatibility but is deprecated.

References: home/…/migrator.go• L142-161 home/…/main.go• L71-77 home/…/main.go• L135-145 home/…/declarative-configuration-management.md• L1

Change checklist

When these files or sections are changed, remember to consider these:

  • Keep the flag name, MEMOS_ environment name, container default, Compose mapping, and health-check port aligned when a listener setting changes.
  • Keep the data-volume path, default SQLite file names, and entrypoint ownership behavior aligned when storage paths or container users change.
  • Keep config-dir, config-apply, the CLI database flags, startup ordering, and the separate apply-job rollout mode aligned when declarative configuration changes.
  • Keep the configuration file schema, resource names, state serial and digest, managed-field rules, and API refusal details aligned across the loader, planner, state record, and service endpoints.
  • Keep resource names and references aligned when user identity changes. Usage limits and other references must still resolve after user renames.
  • Keep write-only secret preservation and response redaction aligned when instance settings, identity providers, or API converters change.
  • Treat version build arguments, release archive names, Docker tags, and the memos version output as one release contract. Keep --version and -V aligned with that output.
  • Keep calendar tag parsing, stable and series image aliases, previous-stable selection, and legacy baseline handling aligned when release rules change.
  • When adding or changing schema files, preserve the schema-version comparison rules and the required upgrade floor described in database provisioning and migrations.
  • When changing log fields or startup summaries, keep connection and secret data separate so operators can diagnose a deployment without exposing credentials.
  • When changing frontend asset output, keep the frontend release step before the container backend build and retain the release smoke check for both fresh and upgraded data.
  • When changing webhook destination policy, keep the allowlist flag, environment binding, deprecated compatibility flag, and private-network guard aligned.
  • When changing rate limiting or trusted-proxy defaults, keep the CLI flags, MEMOS_ names, client-address rules, and request-control behavior aligned.
  • When changing API route prefixes, keep the frontend development proxy, smoke-test route detection, and current-to-legacy upgrade checks aligned with the server routes.
  • When changing release smoke inputs or image ports, keep candidate selection, previous-image selection, readiness probing, and temporary-resource cleanup consistent.
  • When changing release or upgrade workflow paths, keep the smoke-test gate, tag history depth, artifact names, and publication conditions aligned.
  • When changing the backend or frontend workflow filters, keep them broad enough to cover their setup actions and release-facing workflow files without making unrelated runs the only protection.
  • When changing canary image builds, keep the frontend artifact handoff, VERSION and COMMIT build arguments, platform matrix, registry names, and canary manifest tag aligned.
  • When changing installer release names or tag rules, keep version normalization, legacy tag mapping, archive names, checksum entries, and the published release assets aligned.
  • When changing the configuration directory or legacy deployment-file handling, keep the startup warning and the active MEMOS_CONFIG_DIR guidance aligned so old files are not mistaken for active settings.

Important failure modes

TriggerConsequenceGuard
MEMOS_DSN and MEMOS_DSN_FILE are both setThe container exits before Memos startsSet one source only
The data directory cannot be created or accessedProfile validation fails and no database opensMount a writable volume or set a valid MEMOS_DATA path
A configured driver is unknown or its DSN is invalidDatabase setup fails during startupUse sqlite, mysql, or postgres with a valid DSN
The configuration mode is not startup or offStartup stops before the listener opensUse MEMOS_CONFIG_APPLY=startup or off
A configuration file is invalid or a reference cannot be resolvedStartup or config apply stops before a partial configuration is writtenRun memos config validate and provide all referenced values
memos config plan has no existing SQLite databasePlanning stops without creating the databasePass the instance's data directory or DSN, or use config apply for a fresh instance
A desired usage limit names a missing userThe plan is invalid and the apply writes nothingCreate the user first or correct the resource name
An API write changes a field managed by configurationThe API returns FAILED_PRECONDITION and leaves the value unchangedChange the source file and apply it, or release the field with lifecycle rules
A user is named by a managed usage-limit ruleThe user cannot be renamed or deleted until the reference is removed and appliedRemove the reference, apply, then change the user
A mounted legacy deployment file changes while the process runsThe running process keeps the active configuration unchanged and the legacy file has no effectMove the declaration to MEMOS_CONFIG_DIR and apply it
A newer binary starts against a schema that is too old for direct upgradeStartup rejects the installation and requests an intermediate releaseFollow the supported upgrade path before the current release
A binary starts against a newer stored schemaStartup rejects the downgradeRestore the matching or newer binary instead of downgrading in place
A trusted-proxy value is invalidServer construction fails before the listener startsUse valid CIDRs or addresses, or use private or none
A container runs without its data volumeLocal data remains in the disposable container layerMount /var/opt/memos to durable storage
A container image build omits VERSIONThe Docker build stops before it creates the backend binaryPass a calendar development version or release tag from the release version script
Docker, curl, git, or jq is missing from the smoke-test hostThe release smoke check stops before it tests the imageInstall the required tools before running the check
The candidate does not become ready at /healthzThe smoke check fails and prints container logsInspect startup logs and the candidate's port and data-volume setup
The frontend proxy or smoke check uses only one API route generationLocal frontend work or cross-version smoke checks cannot reach the expected APIKeep /api handling and the older /api/v1 fallback aligned with the server routes
The previous stable image cannot be found or equals the candidateThe upgrade check cannot establish a valid release comparisonPass a distinct --previous-image from a stable release
A release tag does not match the calendar formatRelease version extraction stops and no publish job can use itUse YY.MM.N or the matching -rc.N form
No supported stable ancestor exists for an automatic upgrade checkPrevious-image selection fails before the upgrade testPass a distinct stable --previous-image or create a supported release history
The installer cannot map the host OS or CPU to a published archiveInstallation stops before it downloads a binaryUse Linux or macOS on a supported architecture
The requested installer version has no matching archive or checksum entryThe download or checksum step fails before installationUse a published release version and keep its archive and checksum names aligned
A release workflow runs without the full tag historyPrevious stable selection or release-note ranges can be wrongKeep full history and tags for release preparation and smoke checks
A frontend build artifact is missing before a release or canary image buildThe image or binary may lack the web assetsKeep the frontend build and artifact handoff ahead of packaging

Key files

FileWhy to read it
home/…/main.goShows the process configuration surface, declarative apply mode, version commands, legacy-file warning, and startup and shutdown order.
home/…/config.goShows validation, planning, applying, and state inspection for declarative configuration.
home/…/startup_test.goExercises the real startup sequence and checks readiness, fresh install, restart, demo mode, route wiring, and startup configuration.
home/…/config_test.goConfirms the CLI's database behavior, plan exit code, atomic apply path, and state output.
home/…/profile.goDefines profile defaults, data-directory rules, and canonical URL validation.
home/…/configuration.goDefines how configuration files are loaded, merged, and resolved.
home/…/schema.goDefines configurable resource names, supported setting groups, lifecycle rules, and file-level validation.
home/…/plan.goExplains desired-state comparison, references, resource actions, and authentication checks.
home/…/apply.goShows the transaction boundary and the writes made by an apply.
home/…/guard.goDefines how stored ownership prevents conflicting API writes.
home/…/instance_service_configuration.goShows the admin status view and managed-resource refusal contract.
home/…/instance_service.goShows instance setting access, validation, secret preservation, and managed setting checks.
home/…/idp_service.goShows identity-provider administration, validation, and secret redaction.
home/…/auth_service_sso.goShows how an identity-provider sign-in links or provisions a local user.
home/…/user_service.goShows user registration, updates, deletion, and configuration ownership checks.
home/…/user_resource_name.goShows the username-based public identity used by configuration references.
home/…/db.goShows how the selected database backend is chosen.
home/…/migrator.goExplains fresh schema creation, upgrade work, demo seeding, and schema version guards.
/home/user/repo/scripts/DockerfileDefines the release image, data volume, port, runtime user, build toolchain, runtime base, and build metadata.
home/…/entrypoint.shDefines volume ownership, privilege drop, and file-backed DSN behavior.
home/…/compose.yamlShows the smallest Compose deployment with persistent storage and port publishing.
home/…/server.goShows listener selection, readiness, route assembly, trusted-proxy setup, and graceful shutdown.
home/…/version.goDefines release and development version identity.
home/…/install.shShows native release selection, download, checksum, and installation behavior.
home/…/install_test.goVerifies installer version normalization, archive selection, checksum use, and installation output.
home/…/release_version.shDefines accepted release tags, development versions, image aliases, and previous-stable selection.
home/…/release_version_test.goProtects release tag rules, binary-version alignment, and previous-release lookup behavior.
home/…/release_smoke_test.shShows release checks for fresh installs, restarts, frontend assets, API compatibility, and upgrades.
/home/user/repo/web/vite.config.mtsShows the local frontend proxy target and the API route families used during development.
home/…/backend-tests.ymlDefines backend hygiene checks, grouped tests, concurrency, and coverage upload behavior.
home/…/frontend-tests.ymlDefines frontend lint, unit-test, and build gates and their path scope.
home/…/release.ymlConnects smoke checks, version extraction, artifact builds, GitHub releases, and image publication.
home/…/build-canary-image.ymlShows how main-branch commits become multi-architecture canary images.
home/…/upgrade-smoke.ymlRuns migration, installer, release-image, and entrypoint checks at release and pull-request gates.