Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Polykey-CLI: Documentation for Systemd Service Modules in Polykey-CLI #40

Open
13 tasks
CryptoTotalWar opened this issue Apr 9, 2024 · 2 comments
Open
13 tasks
Assignees
Labels
procedure Action that must be executed r&d:polykey:supporting activity Supporting core activity

Comments

@CryptoTotalWar
Copy link
Contributor

Tasks

  • 1. Coordinate a meeting with the engineering team to understand the technical details and user experience implications of the new systemd service modules.
  • 2. Develop comprehensive documentation for both the programs and services module, detailing setup instructions, configuration options, and usage examples.
  • 3. Explain the rationale for separate user-space and system-wide modules and provide guidance on when to use each.
  • 4. Document the default paths for password and recovery code files and describe how users can override these defaults in the module configuration.
  • 5. Address the handling of secret zero within the system and the security best practices to avoid running services as root.
  • 6. Include a troubleshooting section for common issues such as CI failures and connection stability problems.
  • 7. Provide a clear explanation of the current constraints and future potential for configuration consolidation.
  • 8. Ensure that the documentation reflects the latest specifications and changes made in the feature-module branch.
  • 9. Review and incorporate feedback from @tegefaulkes regarding the necessity of a more streamlined setup process.
  • 10. Integrate visual aids like diagrams from the PR into the documentation to aid understanding.
  • 11. Create a draft for review by the team members involved in the PR discussion, specifically @CMCDragonkai, @tegefaulkes, and @brynblack.
  • 12. Finalize the documentation and add it to the appropriate sections in the Polykey-Docs, likely under deployment or service usage.
  • 13. Link back to the original GitHub PR and related issues for reference.

Context

The recent Pull Request #138 in the Polykey-CLI repository introduces significant changes to how the Polykey Agent is activated and managed via systemd services. The PR adds two new module configurations for Polykey-CLI, aimed at streamlining the agent's operation across both user and system spaces.

The 'programs' module configuration facilitates individual user services, enabling personalized management of the Polykey Agent, while the 'services' module configuration caters to a system-wide implementation, similar to how services like Docker operate. These enhancements come as part of a broader initiative to improve the Polykey ecosystem's security, usability, and maintainability.

A crucial aspect of this PR is the handling of secret information, like passwords and recovery codes, which are essential for the secure and stable operation of the Polykey Agent. Moreover, the PR also addresses some of the technical debt by suggesting potential consolidation of configurations in the future and providing more intuitive defaults for users.

Given the importance of these changes, especially in the context of security and ease of use, there is a clear need to document these features comprehensively. This documentation should not only describe the new functionalities and configurations but also guide users through the setup process, provide troubleshooting assistance for common issues, and explain the system's architecture with clarity and precision. The documentation will be a crucial resource for users looking to utilize the Polykey Agent effectively within their workflows.

For background and technical reference, the PR discussion and comments from contributors such as @tegefaulkes and @CMCDragonkai offer insights into the decision-making process and the evolution of the feature's development. These discussions can provide valuable context for the documentation, ensuring that it captures the rationale behind the new modules and their expected use cases.

@CryptoTotalWar CryptoTotalWar added the procedure Action that must be executed label Apr 9, 2024
@CryptoTotalWar CryptoTotalWar self-assigned this Apr 9, 2024
Copy link

linear bot commented Apr 9, 2024

@CryptoTotalWar CryptoTotalWar changed the title Documentation for Systemd Service Modules in Polykey-CLI Polykey-CLI: Documentation for Systemd Service Modules in Polykey-CLI May 22, 2024
Copy link
Contributor Author

The ticket you described fits more aptly within the Reference documentation category rather than a How-to-guide. Here’s why:

  1. Technical Depth and Scope: The ticket involves documenting system modules in depth, including technical specifications, configurations, and system behavior. Reference documentation is suited for detailing such comprehensive and technical content that explains systems and features extensively.
  2. User Reference Needs: The content aims to serve as a point of reference that users or developers can consult to understand the workings and integration of systemd service modules within Polykey-CLI. This includes paths, configurations, usage examples, and security practices.
  3. Integration and Setup Instructions: While it includes setup instructions, these are part of a broader explanation of the systemd service modules' functionality and purpose in Polykey-CLI, leaning more towards informational content rather than a step-by-step procedural guide typical of how-to documentation.

The ticket's focus on explaining intricate details of the systemd integration, handling of secret information, and system-wide versus user-specific service management underscores its alignment with reference documentation, providing essential knowledge and support to users for efficient utilization of Polykey-CLI.

@CMCDragonkai CMCDragonkai added the r&d:polykey:supporting activity Supporting core activity label Aug 15, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
procedure Action that must be executed r&d:polykey:supporting activity Supporting core activity
Development

No branches or pull requests

2 participants