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:
| Form | Operational role | Persistent state |
|---|---|---|
| Docker image | Simple and repeatable production or local deployment | A volume mounted at /var/opt/memos |
| Native binary | Direct installation on Linux or macOS | The configured data directory |
| Docker Compose | A small declarative wrapper around the image | The 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.
| Setting | Default or rule | Operational effect |
|---|---|---|
driver / MEMOS_DRIVER | sqlite | Selects the database backend; startup currently accepts sqlite, mysql, or postgres |
port / MEMOS_PORT | 8081 in the binary; 5230 in the image | Sets the TCP port |
addr / MEMOS_ADDR | Empty | Binds the TCP listener address |
unix-sock / MEMOS_UNIX_SOCK | Empty | Uses a Unix socket and overrides address and port |
data / MEMOS_DATA | Writable /var/opt/memos when available; otherwise the current directory | Selects the local data directory |
dsn / MEMOS_DSN | Derived SQLite file or supplied database source name | Identifies the database connection |
instance-url / MEMOS_INSTANCE_URL | Empty | Sets the canonical external URL |
log-level / MEMOS_LOG_LEVEL | info | Sets log filtering to debug, info, warn, or error |
demo / MEMOS_DEMO | false | Enables SQLite demo data and demo behavior |
config-dir / MEMOS_CONFIG_DIR | /etc/memos/config | Selects the JSON configuration directory |
config-apply / MEMOS_CONFIG_APPLY | startup | Applies configuration at startup; off leaves application to memos config apply |
webhook-private-network-allowlist / MEMOS_WEBHOOK_PRIVATE_NETWORK_ALLOWLIST | Empty | Allows only listed private webhook destinations |
allow-private-webhooks / MEMOS_ALLOW_PRIVATE_WEBHOOKS | false; deprecated | Disables private-network protection for compatibility |
rate-limit / MEMOS_RATE_LIMIT | true | Enables request rate limiting |
trusted-proxies / MEMOS_TRUSTED_PROXIES | private | Selects 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.
| Command | Database behavior | Operational use |
|---|---|---|
memos config validate | Does not open a database | Check file shape and values |
memos config plan | Reads an existing database without creating or migrating it | Preview changes; --detailed-exitcode returns 2 when changes exist |
memos config apply | Creates a new database or migrates it as server startup does | Apply the plan and state record in one transaction |
memos config state | Reads the stored state record | Inspect 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 versionoutput as one release contract. Keep--versionand-Valigned 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,
VERSIONandCOMMITbuild arguments, platform matrix, registry names, andcanarymanifest 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_DIRguidance aligned so old files are not mistaken for active settings.
Important failure modes
| Trigger | Consequence | Guard |
|---|---|---|
MEMOS_DSN and MEMOS_DSN_FILE are both set | The container exits before Memos starts | Set one source only |
| The data directory cannot be created or accessed | Profile validation fails and no database opens | Mount a writable volume or set a valid MEMOS_DATA path |
| A configured driver is unknown or its DSN is invalid | Database setup fails during startup | Use sqlite, mysql, or postgres with a valid DSN |
The configuration mode is not startup or off | Startup stops before the listener opens | Use MEMOS_CONFIG_APPLY=startup or off |
| A configuration file is invalid or a reference cannot be resolved | Startup or config apply stops before a partial configuration is written | Run memos config validate and provide all referenced values |
memos config plan has no existing SQLite database | Planning stops without creating the database | Pass the instance's data directory or DSN, or use config apply for a fresh instance |
| A desired usage limit names a missing user | The plan is invalid and the apply writes nothing | Create the user first or correct the resource name |
| An API write changes a field managed by configuration | The API returns FAILED_PRECONDITION and leaves the value unchanged | Change the source file and apply it, or release the field with lifecycle rules |
| A user is named by a managed usage-limit rule | The user cannot be renamed or deleted until the reference is removed and applied | Remove the reference, apply, then change the user |
| A mounted legacy deployment file changes while the process runs | The running process keeps the active configuration unchanged and the legacy file has no effect | Move the declaration to MEMOS_CONFIG_DIR and apply it |
| A newer binary starts against a schema that is too old for direct upgrade | Startup rejects the installation and requests an intermediate release | Follow the supported upgrade path before the current release |
| A binary starts against a newer stored schema | Startup rejects the downgrade | Restore the matching or newer binary instead of downgrading in place |
| A trusted-proxy value is invalid | Server construction fails before the listener starts | Use valid CIDRs or addresses, or use private or none |
| A container runs without its data volume | Local data remains in the disposable container layer | Mount /var/opt/memos to durable storage |
A container image build omits VERSION | The Docker build stops before it creates the backend binary | Pass a calendar development version or release tag from the release version script |
Docker, curl, git, or jq is missing from the smoke-test host | The release smoke check stops before it tests the image | Install the required tools before running the check |
The candidate does not become ready at /healthz | The smoke check fails and prints container logs | Inspect startup logs and the candidate's port and data-volume setup |
| The frontend proxy or smoke check uses only one API route generation | Local frontend work or cross-version smoke checks cannot reach the expected API | Keep /api handling and the older /api/v1 fallback aligned with the server routes |
| The previous stable image cannot be found or equals the candidate | The upgrade check cannot establish a valid release comparison | Pass a distinct --previous-image from a stable release |
| A release tag does not match the calendar format | Release version extraction stops and no publish job can use it | Use YY.MM.N or the matching -rc.N form |
| No supported stable ancestor exists for an automatic upgrade check | Previous-image selection fails before the upgrade test | Pass a distinct stable --previous-image or create a supported release history |
| The installer cannot map the host OS or CPU to a published archive | Installation stops before it downloads a binary | Use Linux or macOS on a supported architecture |
| The requested installer version has no matching archive or checksum entry | The download or checksum step fails before installation | Use a published release version and keep its archive and checksum names aligned |
| A release workflow runs without the full tag history | Previous stable selection or release-note ranges can be wrong | Keep full history and tags for release preparation and smoke checks |
| A frontend build artifact is missing before a release or canary image build | The image or binary may lack the web assets | Keep the frontend build and artifact handoff ahead of packaging |
Key files
| File | Why to read it |
|---|---|
| home/…/main.go | Shows the process configuration surface, declarative apply mode, version commands, legacy-file warning, and startup and shutdown order. |
| home/…/config.go | Shows validation, planning, applying, and state inspection for declarative configuration. |
| home/…/startup_test.go | Exercises the real startup sequence and checks readiness, fresh install, restart, demo mode, route wiring, and startup configuration. |
| home/…/config_test.go | Confirms the CLI's database behavior, plan exit code, atomic apply path, and state output. |
| home/…/profile.go | Defines profile defaults, data-directory rules, and canonical URL validation. |
| home/…/configuration.go | Defines how configuration files are loaded, merged, and resolved. |
| home/…/schema.go | Defines configurable resource names, supported setting groups, lifecycle rules, and file-level validation. |
| home/…/plan.go | Explains desired-state comparison, references, resource actions, and authentication checks. |
| home/…/apply.go | Shows the transaction boundary and the writes made by an apply. |
| home/…/guard.go | Defines how stored ownership prevents conflicting API writes. |
| home/…/instance_service_configuration.go | Shows the admin status view and managed-resource refusal contract. |
| home/…/instance_service.go | Shows instance setting access, validation, secret preservation, and managed setting checks. |
| home/…/idp_service.go | Shows identity-provider administration, validation, and secret redaction. |
| home/…/auth_service_sso.go | Shows how an identity-provider sign-in links or provisions a local user. |
| home/…/user_service.go | Shows user registration, updates, deletion, and configuration ownership checks. |
| home/…/user_resource_name.go | Shows the username-based public identity used by configuration references. |
| home/…/db.go | Shows how the selected database backend is chosen. |
| home/…/migrator.go | Explains fresh schema creation, upgrade work, demo seeding, and schema version guards. |
/home/user/repo/scripts/Dockerfile | Defines the release image, data volume, port, runtime user, build toolchain, runtime base, and build metadata. |
| home/…/entrypoint.sh | Defines volume ownership, privilege drop, and file-backed DSN behavior. |
| home/…/compose.yaml | Shows the smallest Compose deployment with persistent storage and port publishing. |
| home/…/server.go | Shows listener selection, readiness, route assembly, trusted-proxy setup, and graceful shutdown. |
| home/…/version.go | Defines release and development version identity. |
| home/…/install.sh | Shows native release selection, download, checksum, and installation behavior. |
| home/…/install_test.go | Verifies installer version normalization, archive selection, checksum use, and installation output. |
| home/…/release_version.sh | Defines accepted release tags, development versions, image aliases, and previous-stable selection. |
| home/…/release_version_test.go | Protects release tag rules, binary-version alignment, and previous-release lookup behavior. |
| home/…/release_smoke_test.sh | Shows release checks for fresh installs, restarts, frontend assets, API compatibility, and upgrades. |
/home/user/repo/web/vite.config.mts | Shows the local frontend proxy target and the API route families used during development. |
| home/…/backend-tests.yml | Defines backend hygiene checks, grouped tests, concurrency, and coverage upload behavior. |
| home/…/frontend-tests.yml | Defines frontend lint, unit-test, and build gates and their path scope. |
| home/…/release.yml | Connects smoke checks, version extraction, artifact builds, GitHub releases, and image publication. |
| home/…/build-canary-image.yml | Shows how main-branch commits become multi-architecture canary images. |
| home/…/upgrade-smoke.yml | Runs migration, installer, release-image, and entrypoint checks at release and pull-request gates. |