Feature: Local Filesystem/Docker Mode without Auth for Framna Docs

[ulrikandersen]

Is your feature request related to a problem?

Framna Docs cannot currently be run as a local self-hosted documentation portal from arbitrary files on disk. To use it, GitHub integration and authentication are required, and all documentation must live in remote repositories with GitHub-based access control. That was the original design goal of Framna Docs.

What solution would you like?

Introduce a new "filesystem" mode (toggle via environment variable) so Framna Docs can be launched as a Docker container without authentication, reading directly from a mounted folder. Projects will be detected from local subfolders (e.g., /docs/project-a/openapi.yml), including support for . framna-docs.yml for customization, and displayed in the standard web UI. No GitHub, authentication, or network requests required. Documentation visualization and project browsing should work exactly as with GitHub-backed mode, just purely local.

What alternatives have you considered?

• Creating a separate minimal project for this use case (but this would fork and fragment instead of reusing Framna Docs).

Any additional context?

See attached feasibility analysis in chat: the existing architecture with pluggable repository data sources, clear UI separation, and Docker experience makes this practical as a major new feature.

[ulrikandersen]

Phase 1: Create File System Data Source

Create a new FileSystemRepositoryDataSource that implements IGitHubRepositoryDataSource:

class FileSystemRepositoryDataSource implements IGitHubRepositoryDataSource {
  private readonly baseDirectory: string
  private readonly projectConfigurationFilename: string
  
  constructor(config: {
    baseDirectory: string
    projectConfigurationFilename: string
  }) {
    this.baseDirectory = config. baseDirectory
    this.projectConfigurationFilename = config.projectConfigurationFilename
  }
  
  async getRepositories(): Promise<GitHubRepository[]> {
    // 1. Scan baseDirectory for project folders
    // 2. Look for eligible OpenAPI files (*.yml, *.yaml)
    // 3. Look for .framna-docs.yml config files
    // 4.  Map folder structure to GitHubRepository format
    // 5. Return projects array
  }
}

Expected Directory Structure:

/mounted-docs/
├── project-a/
│   ├── openapi.yml
│   └── .framna-docs.yml (optional)
├── project-b/
│   ├── api-spec. yaml
│   └── .framna-docs.yml

Phase 2: Authentication Bypass Layer

Create an optional "no-auth" mode:

// New NoAuthSession implementing ISession
class NoAuthSession implements ISession {
  async getUserId(): Promise<string> {
    return "local-user" // Single static user
  }
  
  async getIsAuthenticated(): Promise<boolean> {
    return true // Always authenticated
  }
}

Phase 3: File Serving Endpoint

Create a new endpoint to serve local files or extend current blob endpoint:

// /api/local-files/[projectId]/[...filePath]/route.ts
export async function GET(req: NextRequest, { params }) {
  const { projectId, filePath } = params
  const fullPath = path.join(BASE_DIRECTORY, projectId, ...filePath)
  
  // Security: Validate path is within BASE_DIRECTORY
  const normalizedPath = path.normalize(fullPath)
  if (!normalizedPath.startsWith(BASE_DIRECTORY)) {
    return new NextResponse("Forbidden", { status: 403 })
  }
  
  // Read and return file
  const fileContent = await fs.readFile(normalizedPath, 'utf-8')
  return new NextResponse(fileContent, {
    headers: { "Content-Type": "text/plain" }
  })
}

Phase 4: Configuration

Add new environment variables:

# New Variables
FRAMNA_DOCS_MODE=filesystem  # or "github"
FRAMNA_DOCS_BASE_DIRECTORY=/app/docs
FRAMNA_DOCS_ENABLE_AUTH=false

# Make these optional when filesystem mode:
GITHUB_CLIENT_ID=
GITHUB_CLIENT_SECRET=
GITHUB_APP_ID=
GITHUB_PRIVATE_KEY_BASE_64=
POSTGRESQL_HOST=
REDIS_URL=

Phase 5: Composition Root Updates

Modify src/composition.ts to conditionally wire dependencies:

const mode = env.get("FRAMNA_DOCS_MODE") || "github"

const repositoryDataSource = mode === "filesystem" 
  ? new FileSystemRepositoryDataSource({
      baseDirectory: env.getOrThrow("FRAMNA_DOCS_BASE_DIRECTORY"),
      projectConfigurationFilename: env.getOrThrow("FRAMNA_DOCS_PROJECT_CONFIGURATION_FILENAME")
    })
  : new GitHubRepositoryDataSource({
      // existing GitHub config
    })

const session = env.get("FRAMNA_DOCS_ENABLE_AUTH") === "false"
  ? new NoAuthSession()
  : new AuthjsSession({ auth })

---

🚧 Challenges & Considerations

1. Version Management

• Current: Git branches and tags naturally provide versions
• Solution: ?

2. File Watching

• Challenge: Detecting file system changes without restarting
• Solution: Implement file watching or require manual refresh

3. Security

• Risk: Path traversal attacks when serving files
• Solution: Strict path validation, sandboxing to mounted directory

4. Database Dependency

• Current: PostgreSQL stores user sessions and cached data
• Solution: Make optional; use in-memory storage for filesystem mode